Nodus

Add agent packages to your repo with one command.

Nodus installs agent packages from GitHub, Git URLs, or local paths, locks the exact revision, and writes only the adapter runtime files your repo actually uses.

English • 简体中文

Install • For AI Assistants • Quick Start • CLI Help • Learn More • Contributing

What Is Nodus?

Nodus is a package manager for repo-scoped agent tooling.

If a package publishes content such as skills/, agents/, rules/, or commands/, Nodus can:

• add it from GitHub, Git, or a local path
• record what you asked for in nodus.toml
• lock the exact resolved revision in nodus.lock
• write managed files into adapter roots such as .codex/, .claude/, .cursor/, .github/, .agents/, or .opencode/
• compose managed MCP server config for supported runtimes, including .mcp.json, .codex/config.toml, and opencode.json
• prune stale generated files without touching unmanaged ones

For most teams, the normal flow is:

nodus add <package> --adapter <adapter>
nodus doctor

Install

Install from crates.io:

cargo install nodus

Building from source requires Rust 1.88.0 or newer.

Install the latest prebuilt binary on macOS or Linux:

curl -fsSL https://nodus.elata.ai/install.sh | bash

Install with Homebrew:

brew install nodus-rs/nodus/nodus

Install the latest prebuilt binary on Windows with PowerShell:

irm https://nodus.elata.ai/install.ps1 | iex

Windows install command failed?

If the command fails, install PowerShell 7, restart your terminal, then run:

winget install --id Microsoft.PowerShell --source winget
pwsh -NoProfile -Command "irm https://nodus.elata.ai/install.ps1 | iex"

For AI Assistants

If you want an AI assistant to operate Nodus for you, give it the fetchable prompt URL:

• https://nodus.elata.ai/prompts/README.md

That prompt gives the assistant concrete Nodus operating instructions, helps it choose the right nodus add command, and still ends with nodus doctor.

Quick Start

Install a package into the current repo and verify the result:

nodus add nodus-rs/nodus --adapter codex
nodus doctor

That flow:

• creates nodus.toml if the repo does not have one yet
• records the dependency in nodus.toml
• resolves and locks the exact revision in nodus.lock
• writes the managed runtime files for the selected or detected adapter

If the package publishes mcp_servers, Nodus now carries that MCP config into the repo's managed runtime outputs as well. Today that includes the legacy project .mcp.json, Codex .codex/config.toml, and OpenCode opencode.json.

If the package is a wrapper that exposes multiple child packages, nodus add now records the wrapper itself and leaves child packages disabled until you either edit members in nodus.toml or opt in up front with --accept-all-dependencies.

If you want a user-level install instead of repo-scoped state, use --global explicitly:

nodus add nodus-rs/nodus --global --adapter codex

Hook Support Matrix

When a package publishes [[hooks]], Nodus filters those hook intents by what each adapter can actually emit today.

Adapter	Native hook events	session_start sources
claude	session_start, user_prompt_submit, pre_tool_use, post_tool_use, stop, session_end	startup, resume, clear, compact
codex	session_start, pre_tool_use, post_tool_use, stop	startup, resume
opencode	session_start, pre_tool_use, post_tool_use, stop	startup
agents	none	none
copilot	none	none
cursor	none	none

If you want to inspect the exact matrix for one package, run:

nodus info <package> --json

That output now includes adapter hook capability data derived from the same rules Nodus uses during sync.

Packages that intentionally ship Claude plugin hook config from a hooks/ folder can declare it explicitly in nodus.toml with claude_plugin_hooks = ["hooks/hooks.json"]. This keeps the behavior adapter-specific for Claude and uses the existing CLAUDE_PLUGIN_ROOT compatibility path instead of portable native [[hooks]].

CLI Help

nodus --help is the main command guide.

Start there when you want to learn the workflow, then open command-specific help as needed:

nodus --help
nodus add --help
nodus sync --help
nodus doctor --help

Commands most users need:

• nodus add <package> --adapter <adapter> to install a package into the current repo
• nodus info <package-or-alias> to inspect a package before or after install
• nodus sync to rebuild managed outputs from the versions already recorded
• nodus update to move dependencies to newer allowed revisions
• nodus remove <alias> to remove a dependency and prune what it owned
• nodus clean to clear shared repository, checkout, and snapshot cache data without changing project manifests or managed outputs
• nodus doctor to check that the repo, lockfile, shared store, and managed outputs still agree

Learn More

• Docs: https://nodus.elata.ai/docs/
• Install guide: https://nodus.elata.ai/install/
• Package command generator: https://nodus.elata.ai/packages/
• Consumer manifest example: examples/nodus.toml
• Package author manifest example: examples/package-author.nodus.toml

For package authoring details, workspace packaging, managed exports, or relay workflows, prefer the website docs and nodus --help over treating this README as the full command reference. That applies to MCP packages too: package authors can publish mcp_servers in nodus.toml, and consumers get the matching managed project config for the adapter they use.

Contributing

See CONTRIBUTING.md for local development and release checks.

License

Licensed under Apache-2.0.