A local capability and integration manager for MCP stacks, CLI tools, runtimes, and externally installed AI Agent Hosts.
RUDI installs and manages its local capability infrastructure and integrates with provider-owned agent software:
npm install -g @learnrudi/cli
rudi init --skip-downloads
rudi home
Install Node.js 22 or 24.22+ and npm first. npm installs the CLI executable and its
dependencies into your npm prefix; it does not create ~/.rudi/. Initialization
creates the local RUDI directories and settings. It also installs a managed
RUDI instruction block in your Codex home; add --no-agent-instructions to skip
that integration.
This source includes the initialization and npm-inventory fixes first verified
against 1.10.29: rudi init uses the verified registry installer and returns
nonzero on incomplete setup; rudi list includes dynamic npm tools. Check
rudi --version and the installed package’s engines before applying source
guidance to a published release.
Registry and CLI releases are independent. The Registry’s accepted
Node manifest
was 24.21.0 at the October 20, 2026 source review. That still falls below this
checkout’s Node 24 minimum. Keep a supported Node on PATH and recheck the
manifest and this package’s engines when selecting a runtime.
Node 24.19–24.21 can abort while collecting native SQLite objects. This checkout requires
24.22+ on the Node 24 line and rejects older versions before opening Agent Host
state. pnpm build exercises allocation-driven SQLite GC and worker teardown;
the packaged scripts/verify-sqlite-teardown.mjs provides the same acceptance
probe against the package’s own dependency. No installed runtime is upgraded
automatically. See the teardown verification.
--skip-downloads initializes local structure without installing runtimes. See the
fresh-install findings and verification guide
for dated test evidence and the remaining registry compatibility gap.
Shims are opt-in. If you want PATH exposure for installed tools:
rudi shims rebuild
export PATH="$HOME/.rudi/bins:$PATH"
When you opt in (rudi shims rebuild), tools installed through RUDI get a wrapper script or symlink (shim) in ~/.rudi/bins/. This provides:
Runtime symlinks created by rudi init --with-shims and rudi shims rebuild
use relative targets. They keep pointing to the same installed files when the
RUDI home is accessed through another path, including an SMB mount. This does
not make command wrappers or runtime execution portable between machines.
When you run tsc, the shell finds ~/.rudi/bins/tsc, which delegates to the actual TypeScript installation at ~/.rudi/binaries/npm/typescript/node_modules/.bin/tsc.
RUDI supports four installation sources:
npm:<package>) - Any npm package with a bin fieldMCP stacks often require API keys and tokens. RUDI stores secrets in ~/.rudi/secrets.json (mode 0600) and injects them as environment variables when running stacks. Secrets are never exposed in process listings or logs.
# Install any npm CLI tool
rudi install npm:typescript # Installs tsc, tsserver
rudi install npm:@stripe/cli # Installs stripe
rudi install npm:vercel # Installs vercel
# Install from curated registry
rudi install slack # MCP stack for Slack
rudi install binary:ffmpeg # Upstream ffmpeg binary
rudi install binary:supabase # Supabase CLI
# Install a RUDI-compatible stack from a public GitHub tree
rudi install https://github.com/acme/rudi-packages/tree/main/catalog/stacks/demo
# Install with scripts enabled (when needed)
rudi install npm:puppeteer --allow-scripts
# Optional: create shims immediately (opt-in)
rudi install binary:ffmpeg --with-shims
Curated npm tools can declare install.nodeRuntime to use a separate managed
Node runtime for installation, registry post-install commands, and execution.
The installer honors the catalog’s tool version and explicit runtime binding;
availability of those pins and bindings depends on the published catalog.
The binding survives rudi shims rebuild. The shared node, npm, and
npx commands retain their existing runtime. A missing bound runtime produces
an error instead of falling back to another Node version.
For development, use pnpm test. The local wrapper may select the managed Node
when existing native dependencies require it. To verify a specific supported
Node version, install dependencies in a separate checkout using that Node and run
RUDI_CLI_TEST_WRAPPER_ACTIVE=1 pnpm test with its bin directory first in PATH.
CI enforces this under both Node 22 and 24; do not reuse native modules built
for a different Node ABI. pnpm build updates this checkout’s
distribution files; it does not update the installed rudi command. Use
node dist/index.cjs <command> to exercise the rebuilt checkout with your
selected working Node. Regenerating active launchers is a separate installation
step and must use the intended CLI version.
Downloaded runtime updates are verified and extracted in a sibling staging
directory before replacing the installed runtime. Failed downloads, invalid
executables, and lockfile-write failures preserve the previous runtime. A
successful replacement retains its previous directory at the returned
backupPath; retain it until the new runtime and its consumers are accepted.
Concurrent runtime installs fail with the lock path in the error. If a process
is interrupted, inspect the lock’s PID and retained directories before removing
a stale lock or resuming; automatic crash recovery is not provided.
Runtime locks use runtime-tree-v1: they include bundled dependencies and
permit only symlinks resolving within the installation. Other package locks
retain their existing checksum rules. Keep the matching CLI version when
verifying or rolling back a runtime that uses this checksum mode.
GitHub source installs accept only the exact public HTTPS form
https://github.com/<owner>/<repo>/tree/<ref>/<stack-path>. RUDI resolves the
ref to a full commit SHA, downloads only files and directories from that pinned
subtree, rejects symlinks/submodules and foreign download URLs, and records the
source plus a content checksum in the package lockfile. Private repositories,
other Git hosts, repository-root shorthand, and arbitrary non-RUDI source are
not supported.
The external stack must use a canonical stack: manifest. Its related
metadata must name the operator skill in operatorSkill and skills, and must
add operatorSkillPath as a repository-relative bundle directory containing
SKILL.md:
{
"related": {
"operatorSkill": "skill:demo",
"skills": ["skill:demo"],
"operatorSkillPath": "catalog/skills/demo"
}
}
Downloaded GitHub code is not executed during installation by default: Node
dependency lifecycle/build scripts are suppressed, and Python requirements that
may run package builds are rejected. MCP indexing is also deferred because it
launches the stack command. Use --allow-scripts only after reviewing the pinned
source and dependencies; that opt-in permits dependency/build execution and
post-install tool indexing.
rudi list # All installed packages
rudi list stacks # MCP stacks only
rudi list binaries # CLI tools only
rudi list runtimes # Language runtimes
rudi list agents # External Agent Host readiness
rudi search pdf # Search for packages
rudi search --all # List all available packages
rudi search --stacks # Filter to MCP stacks
rudi search --binaries # Filter to CLI tools
rudi search --all --skills --category=web --role=operator
rudi search --all --skills --domain=real-estate
rudi list skills --capability=review
rudi info skill:vercel
rudi secrets list # Show configured secrets (masked)
rudi secrets set SLACK_BOT_TOKEN # Set a secret (prompts for value)
rudi secrets set OPENAI_API_KEY "sk-..." # Set with value
rudi secrets get OPENAI_API_KEY # Print raw value for scripts only
rudi secrets remove SLACK_BOT_TOKEN # Remove a secret
See Frontier Agent Hosts for the complete Claude, Codex, Antigravity, and Gemini headless command matrix, current model aliases, resume/workspace/JSON controls, and the Google authentication split.
rudi shims rebuild # Create rudi-router and rudi-mcp shims (opt-in)
rudi integrate claude # Add the RUDI router to Claude config
rudi integrate codex # Add the RUDI router to Codex config
rudi integrate gemini # Add the RUDI router to Gemini config
rudi integrate antigravity # Add the RUDI router to Antigravity config
rudi integrate all # Add the router to all detected agents
This modifies the agent’s MCP configuration to include one managed RUDI router; stack discovery and secret injection stay inside RUDI.
Every registry stack declares a primary operator skill. A normal stack install installs that skill automatically and reconciles it through the same native projection coordinator used for Codex, Claude, Gemini, and Antigravity. Additional companion workflows remain optional:
rudi install stack:video-editor # operator skill included
rudi install stack:video-editor --with-related-skills # include companions
rudi install stack:video-editor --no-related-skills # operator only
In Claude Code, invoke the operator as /skill-name. In Codex, use /skills
to select it or mention it as $skill-name. The operator guides the host
through the stack’s MCP tools; users do not need to know the individual tool
names.
~/.rudi/skills is the canonical installed package layer. Each native host has
a derived complete-tree projection, with per-host/per-skill ownership receipts
under ~/.rudi/state/native-skills/<host>/. Each receipt binds the source-file,
complete canonical-package, and rendered-tree digests to the exact target. A direct skill install reconciles
only that skill to configured native hosts by default; select hosts explicitly
or opt out when needed:
rudi install skill:rudi-diagnose
rudi install skill:rudi-diagnose --sync-skills=codex,claude
rudi install skill:rudi-diagnose --no-sync-skills
Reconciliation creates missing trees, adopts an identical legacy tree, updates
an unchanged managed tree, and replaces the whole directory so stale files are
pruned. A tree that differs from its receipt is drifted; a collision without
a receipt is unmanaged. Both are preserved until the user reviews the exact
skill and supplies scoped --force. Whole-inventory force additionally
requires --all:
rudi skills sync codex # reconcile/adopt without replacing conflicts
rudi skills sync claude
rudi skills sync gemini
rudi skills sync antigravity
rudi skills sync codex skill:rudi-change-map skill:rudi-engineering-gate --force
rudi skills sync claude skill:rudi-change-map --force
rudi skills sync codex --all --force # explicit, reviewed whole-inventory replacement
Every result reports restartRequired when host state changed. Restart active
native sessions to load the new projection; RUDI does not claim hot reload.
rudi check skill:<id> --json reports the canonical package and all four host
states. rudi agent hosts --json counts only receipt-backed, digest-matching
trees as synchronized; unrelated skill directories do not qualify.
Private native names and host restrictions can be configured in
$RUDI_HOME/native-skills.json (default ~/.rudi/native-skills.json):
{
"schemaVersion": 1,
"skills": {
"skill:image-generator": { "name": "image-generate" },
"skill:codex-project-task-archiver": { "hosts": ["codex"] }
}
}
Package IDs, canonical directories, lockfiles, and receipt filenames stay stable:
install/update/check/remove still use skill:image-generator; the native folder,
frontmatter name, and exact self-invocations use image-generate. Omitted name
keeps the package name. Omitted hosts permits all supported hosts; an empty
array excludes all hosts. Reconciliation returns excluded on disallowed hosts
without creating or removing a tree, including with --force. Explicit package
removal still cleans unchanged receipt-owned trees on previously allowed hosts. This is private local policy and
does not rename public registry packages.
Policy objects reject unknown fields, unsupported versions, invalid names, unknown/duplicate hosts, duplicate target names, and symlinked paths. A name reserved by another policy entry or owned by another package cannot be taken over, including with force. Invalid policy prevents native reconciliation.
Receipt schema 3 records the stable skillId separately from the native
skillName; schema 2 remains readable. During a rename, an existing old target
blocks reconciliation. After that target has been deliberately preserved or
relocated, sync adopts an exact rendered new tree and updates the same receipt
atomically. A customized new tree remains unmanaged and the prior receipt is
retained; normal sync never recreates the retired name. A missing new tree may
be created. Use --dry-run to inspect these decisions first. Removal follows
the receipt’s recorded target and digest, preserving unowned or changed trees.
Changing policy does not automatically move or delete existing directories.
Older CLI versions cannot read schema 3 receipts. Keep receipt backups when rolling out this feature; reverting the executable alone is not a complete rollback. Keep the new CLI and private policy together on every participating workstation before running native reconciliation there.
rudi agent is the supported headless execution surface. Foreground launches
run directly through the shared CLI core and require no daemon. Native
providers continue to own their complete transcripts; RUDI stores only a
bounded launch/workspace projection and durable launch artifacts.
# Inspect native installations, auth, RUDI router wiring, skills, and versions
rudi agent hosts
rudi agent models claude
rudi agent models codex
rudi agent models antigravity # `google` remains an accepted alias
rudi agent models gemini
# Writable Git projects automatically receive a dedicated worktree
rudi agent launch codex \
--workspace . \
--prompt "Fix the failing tests"
# Read-only work uses the project directly
rudi agent launch claude \
--workspace . \
--read-only \
--prompt-file task.md
# stdin and provider-specific argv are supported
printf '%s' "Explain this repository" | \
rudi agent launch google --workspace . --read-only --json
rudi agent launch codex \
--workspace . \
--prompt "Review the installer" \
-- --strict-config
# Resume the same provider-owned native session
rudi agent resume <launch-id> --prompt "Continue with the next failure"
# Inspect minimal persisted launch projections
rudi agent list --json
rudi agent status <launch-id> --json
Workspace defaults fail closed:
| Project | Access | Execution workspace |
|---|---|---|
| Git repository | Writable | New Git worktree |
| Git repository | Read-only | Project root directly |
| Non-Git directory | Writable | Isolated copied workspace |
| Non-Git directory | Read-only | Directory directly |
RUDI never initializes Git, never falls back to $HOME, and never degrades a
failed isolated write launch into shared write access. Detached launches,
reconnect, stop, diff, promote/discard, and provider-neutral groups use the
local background service and dedicated workers:
rudi agent launch codex --workspace . --prompt-file task.md --detach
rudi agent attach <launch-id>
rudi agent diff <launch-id>
rudi agent promote <launch-id> # or: rudi agent discard <launch-id>
rudi agent group launch \
--workspace . \
--task claude:security.md \
--task codex:implementation.md \
--task google:ux.md \
--detach
These dedicated workers survive terminal closure and daemon restarts. The versioned Agent Host service is a control plane, not the owner or source of truth for provider sessions or transcripts.
rudi pkg slack # Show package details
rudi pkg npm:typescript # Show shims and paths
rudi shims list # List all shims
rudi shims check # Validate shim targets exist
rudi update stack:slack # Update one stack and rebuild its tool index
rudi update stack:slack --preserve-state # Opt in to preserving install-local state paths
rudi update skill:rudi-diagnose # Reconcile already-managed host projections
rudi update --all # Explicitly update the whole installed inventory
rudi remove skill:rudi-diagnose # Remove only unchanged RUDI-owned projections
rudi remove slack # Uninstall a package
rudi doctor # Check system health
For a stack that declares a suite through Registry related.skills, use
--with-related-skills to update the stack plus only those related skill
packages that are already installed. Missing related skills are reported and
skipped; update never turns them into implicit installs. Exact skill updates
reconcile already-managed host projections without blanket force.
--sync-skills explicitly selects hosts and still projects only skill IDs
updated by this command:
# Resolve the exact package, index, and Codex projection plan without those writes.
# Registry metadata is refreshed in memory without persisting the cache.
rudi update stack:swe-engineering --with-related-skills --sync-skills=codex --dry-run --json
# Apply the same bounded suite update and reconcile only its affected Codex projections.
rudi update stack:swe-engineering --with-related-skills --sync-skills=codex
Use --no-sync-skills to suppress projection reconciliation. Drifted and
unmanaged update targets remain intact unless one exact selected skill is
updated with scoped --force.
rudi update without a package now fails closed; use --all when broad scope
is intentional. Update JSON mode emits one structured document. Install keeps
human progress output and rejects --json instead of mixing formats.
Packages installed from GitHub are immutable snapshots: an explicit update
stops with guidance, while --all reports and skips them. To move to another
ref or commit, rerun rudi install <github-tree-url> --force.
Names from the removed imported-session and RUDI-owned execution architecture remain visible only as migration notices. They exit nonzero and never load legacy runtime code:
rudi help db # Existing rudi.db is preserved but not opened
rudi help session # Use the provider-native transcript
rudi help parallel # Use native orchestration or rudi agent group
rudi help run-group # Use rudi agent group
Removed /agent/* and /sessions/* endpoints have no compatibility adapter.
Core CLI and daemon paths do not initialize, open, repair, or require
rudi.db.
This is the machine-local installation and data directory. The CLI source tree is separate; see the annotated repository tree and execution trace.
~/.rudi/
├── stacks/ # Installed MCP stack package code
├── skills/ # Installed reusable skill definitions
├── workflows/ # Installed workflow definitions
├── runtimes/ # Managed language runtimes
├── binaries/ # Managed third-party CLI tools
├── agents/ # Legacy agent-package migration metadata (not executable authority)
│
├── bins/ # Current command shims and router entrypoints
├── shims/ # Legacy shim directory for older integrations
├── router/ # Local MCP router and permission-hook runtime files
│
├── state/ # Persistent per-stack runtime state
│ ├── agent-hosts.db # Minimal Agent Host lifecycle projection
│ └── stacks/
│ └── google-workspace/
│ └── accounts/ # OAuth tokens and selected account state
├── secrets/ # Stack-specific secret/env files
├── secrets.json # Primary secret store (mode 0600)
│
├── rudi.json # Installed package and stack configuration
├── settings.json # Local settings
├── shim-registry.json # Shim ownership tracking
│
├── cache/ # Rebuildable registry/package/tool-index cache
├── locks/ # Package install lock files
├── logs/ # Daemon and runtime logs
├── artifacts/
│ └── agent-launches/ # Per-launch worktrees or isolated copied workspaces
├── notes/ # Local user artifacts from RUDI workflows
├── archive/ # Manual cleanup archives
├── prompts/ # Legacy prompt directory; new assets map to skills/
│
├── rudi.db # Retired session data; preserved and never opened by CLI
├── rudi.db-wal # Retired SQLite journal, if already present
├── rudi.db-shm # Retired SQLite shared memory, if already present
├── daemon.port # Active loopback daemon port (mode 0600)
└── daemon.token # Active loopback daemon token (mode 0600)
Use rudi home for a lifecycle-oriented view of this tree. It labels each path
as installed code, persistent state, secret material, generated cache,
operational logs, or retired preserved data. Use rudi home --json for
machine-readable output. Core commands do not create or open rudi.db.
When you run rudi integrate claude, RUDI:
rudi server entry pointing to ~/.rudi/bins/rudi-router.When Claude invokes the MCP server:
rudi-router loads the generated tool index from
~/.rudi/cache/tool-index.json.This architecture means secrets stay local and are never written to agent config files.
Put non-secret, machine-specific MCP settings in $RUDI_HOME/router-settings.json
(~/.rudi/router-settings.json by default). This optional file is separate from
installer-owned rudi.json and stack directories, so stack updates and
re-registration do not replace it. Use restrictive file permissions, such as
0600. Example (replace the model path with the actual installed file):
{
"schemaVersion": 1,
"stacks": {
"stack:audio-tools": {
"env": {
"AUDIO_TOOLS_WHISPER_MODEL": "/absolute/path/to/ggml-large-v3-turbo.bin"
},
"toolTimeoutMs": {
"audio_transcribe": 900000
}
},
"stack:speech-generator": {
"toolTimeoutMs": {
"generate_speech": 150000
}
}
}
}
The local stdio router reads this file at startup; reconnect the MCP server after
editing it. These settings do not configure hosted routers or the direct
rudi run / rudi mcp commands. The environment order is inherited values,
selected stack settings, declared secrets, then the existing managed PATH setup.
Keep credentials in the secret store; do not put them in env.
toolTimeoutMs uses the stack’s original tool name and accepts integer
milliseconds from 1 through 900000 (15 minutes). Speech generate_speech defaults
to 150 seconds, allowing its 120-second provider budget plus overhead. Other
unconfigured calls, initialization, and discovery keep the 30-second deadline.
Explicit settings override these defaults. Choose a deadline covering the tool’s
own processing budget; for local audio this includes probing, conversion, and
Whisper. The host’s MCP tool timeout must also allow that duration (for example,
960 seconds for a 900-second downstream budget plus initialization). Increasing
the router deadline does not increase the tool’s own execution limit.
Malformed, unsupported, or oversized settings stop router startup with a
diagnostic; values are never included in that diagnostic. A tool deadline error
does not cancel downstream work or retry it. It includes a Result file path
under $RUDI_HOME/outputs/router-results/. Read that private JSON receipt before
retrying: pending means the stack has not returned; completed contains the
original JSON-RPC response, including tool/provider errors; interrupted means
the stack or router stopped without a known result. A completed response is not
necessarily a successful tool action: inspect its error, result.isError, and
tool-specific payload. Inputs and environment are omitted; returned content can
be sensitive, so receipts use owner-only permissions and stay on the local Mac.
Receipts are retained until explicitly removed. Remove an override to restore its
default, or remove the file to restore all defaults, then reconnect.
Timed-out calls remain active for pool cleanup until the stack returns or stops.
The router admits at most 128 outstanding requests and failed receipt writes;
at capacity it rejects new work before dispatch. If receipt storage is
temporarily unavailable, it retains the latest result in memory, reports the
failure on stderr, and retries only the local write during pool cleanup. No
provider call is replayed. Abrupt process loss or shutdown while storage remains
unavailable can still lose in-memory data. A pending receipt whose routerPid
is no longer running has an unknown outcome; inspect artifacts before retrying.
By default, npm packages install with --ignore-scripts to prevent arbitrary code execution during install. If a package requires lifecycle scripts (e.g., native compilation), use:
rudi install npm:puppeteer --allow-scripts
Secrets are stored in ~/.rudi/secrets.json with file permissions 0600 (owner read/write only). This matches the security model used by SSH, AWS CLI, and other credential stores.
Each package installs to its own directory. Shims are thin wrappers that set up the environment and delegate to the real binary. This prevents packages from interfering with each other.
The registry inventory changes independently of the CLI. Discover the current catalog instead of relying on a checked-in list:
rudi search --all --stacks
When a registry package declares lifecycle metadata, package search, listings,
and rudi info show its maturity, support posture, and any deprecation,
replacement, or removal guidance. Packages without lifecycle metadata are
unclassified; the CLI does not infer support from version numbers.
| Binary | Description | Source |
|---|---|---|
| ffmpeg | Video/audio processing | Upstream |
| ripgrep | Fast text search | Upstream |
| supabase | Supabase CLI | npm |
| vercel | Vercel CLI | npm |
| uv | Python package manager | Upstream |
Ensure ~/.rudi/bins is in your PATH:
echo $PATH | grep -q '.rudi/bins' && echo "OK" || echo "Add ~/.rudi/bins to PATH"
Run rudi shims check to validate all shims. If a target is missing, reinstall the package:
rudi remove npm:typescript
rudi install npm:typescript
rudi list stacksrudi integrate claudeEnsure correct permissions:
chmod 600 ~/.rudi/secrets.json
MIT
Stacks and skills use seven primitive categories: web, code, data, documents, media,
communication and agents. Capability, domain and provider values are read from
capability:, domain: and provider: tags. Search and list accept
--category, --capability, --domain, --provider and --role filters.
--role=workflow refers to a skill’s role; --workflows still selects the
separate workflow package kind.
Stacks expose the same facets in search, installed listings and
rudi info stack:<id> --json, without skillRole or operatorFor fields.
For example, rudi search --all --stacks --provider=vercel --capability=deploy
finds the deployment stack, and rudi list stacks --category=web filters the
installed inventory. The role filter applies only to skills.
The primary operator role is derived from a stack’s related.operatorSkill.
Requiring a stack does not make a workflow its operator. Skill JSON includes
skillRole, operatorFor and facets; installed inventory uses local/cached
catalog context without a network request and reports unknown role for external
or unidentified installs. rudi info skill:<id> reads the actual skill entrypoint
and supports --json.
Canonical skill packages install as ~/.rudi/skills/<id>/SKILL.md; legacy flat
installs remain readable. Updating an owned skill stages the complete package,
verifies existing content against the installation checksum, replaces the
source and writes the new lock. Failed updates restore the prior source and
lock when recovery is safe. Edited files and missing ownership evidence are
preserved, even when update internally requests reinstall. rudi update skill:<id>
--dry-run --no-sync-skills checks ownership and reports the proposed migration
without replacing content. Files excluded from historical checksums also block
replacement until their ownership is reconciled.
Successful replacements retain the previous file/tree under a hidden transaction
folder, return backupPath in the install result and print it during updates.
This preserves late writes through already-open files. Reconcile these backups
before any separately authorized cleanup; the updater never deletes them automatically.
Same-ID loose-file/folder collisions are explicit errors for path resolution
and native sync; rudi list skills exposes their paths for reconciliation.
If a concurrent edit prevents rollback, preserve the reported transaction
folder and resolve its contents and .install-lock before retrying. Do not
remove a recovery guard until its prior package and edited replacement have
been accounted for.
Native projections retain complete trigger descriptions and bundled Codex metadata. Ownership receipts, exact force scope, conflict preservation and restartRequired reporting continue to govern native updates. Deploy the compatible CLI before publishing a registry that migrates existing flat skills.
Registered shared task execution is described in the Agent Host task contract. Compute owns manual and recurring admission; Agent Host provides foreground completion through a launchd custody capsule on qualified hosts. Explicit unlimited duration is supported with matching zero timeouts; cleanup, output limits and qualification gates remain active. Source support does not establish an installed release, deployment or schedule activation.
Documentation ownership and the review requirements are in AGENTS.md.