RUDI CLI MCP server

RUDI CLI

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:

• MCP Stacks - Model Context Protocol servers for Claude, Codex, and Gemini
• CLI Tools - Any npm package or upstream binary (ffmpeg, ripgrep, etc.)
• Runtimes - Node.js, Python, Deno, Bun
• Agent Host integration - Discovery, readiness checks, MCP wiring, and launch support for vendor-installed Claude, Codex, Gemini, and Antigravity

Installation

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"

Core Concepts

Shim-Based Architecture

When you opt in (rudi shims rebuild), tools installed through RUDI get a wrapper script or symlink (shim) in ~/.rudi/bins/. This provides:

• Clean PATH integration without modifying system directories
• Version isolation per package
• Ownership tracking for clean uninstalls
• Consistent invocation across different package sources

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.

Package Sources

RUDI supports four installation sources:

1. Dynamic npm (npm:<package>) - Any npm package with a bin field
2. Curated Registry - Pre-configured stacks and binaries with documentation
3. Public GitHub stacks - Commit-pinned RUDI stack directories
4. Upstream Binaries - Direct downloads from official sources

Secret Management

MCP 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.

Usage

Installing Packages

# 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.

Listing Installed Packages

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

Searching the Registry

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

Managing Secrets

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

Integrating with AI Agent Hosts

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.

Running Headless Agent Hosts

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.

Inspecting Packages

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

Maintenance

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.

Retired Commands

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.

Directory Structure

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.

How MCP Integration Works

When you run rudi integrate claude, RUDI:

1. Reads the target host's MCP configuration.
2. Writes one rudi server entry pointing to ~/.rudi/bins/rudi-router.
3. Removes obsolete direct RUDI stack entries that the managed router replaces.

When Claude invokes the MCP server:

1. rudi-router loads the generated tool index from ~/.rudi/cache/tool-index.json.
2. It maps the requested tool to its installed stack.
3. It loads only that stack's declared secrets and injects them as environment variables.
4. It launches the stack MCP server and proxies the request/response.

This architecture means secrets stay local and are never written to agent config files.