nodus 0.4.0

What Is Nodus?

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

If a package publishes content under folders like skills/, agents/, rules/, or commands/, Nodus can:

• add it from GitHub, Git, or a local path
• pin what you asked for in nodus.toml
• lock the exact resolved revision in nodus.lock
• write managed files into .codex/, .claude/, .cursor/, .agents/, or .opencode/
• prune stale generated files without touching unmanaged ones

For most users, the main command is:

nodus add <package>

Install

Install from crates.io:

cargo install nodus

Install the latest prebuilt binary on macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/WendellXY/nodus/main/install.sh | bash

Install with Homebrew:

brew install WendellXY/nodus/nodus

Quick Start

Install a package for Codex:

nodus add WendellXY/nodus --adapter codex

That one command:

• creates nodus.toml if your repo does not have one yet
• records the dependency in nodus.toml
• resolves the latest tag by default
• locks the exact resolved revision in nodus.lock
• writes managed runtime files for the selected adapter

Validate the result:

nodus doctor

Typical output files look like this:

.codex/skills/<skill-id>_<source-id>/
.claude/skills/<skill-id>_<source-id>/
.cursor/rules/<rule-id>_<source-id>.mdc

nodus add

Add from GitHub:

nodus add owner/repo --adapter codex

Add from a local path:

nodus add ./vendor/playbook --adapter codex

Pin a tag, branch, commit, or semver range:

nodus add owner/repo --tag v1.2.3
nodus add owner/repo --branch main
nodus add owner/repo --revision 0123456789abcdef
nodus add owner/repo --version '^1.2.0'

Install only part of a package:

nodus add owner/repo --adapter claude --component skills
nodus add owner/repo --adapter claude --component skills --component rules

Add a dev-only dependency:

nodus add owner/repo --dev --adapter codex

Start tools with automatic sync:

nodus add owner/repo --adapter codex --sync-on-launch

Preview changes without writing them:

nodus add owner/repo --adapter codex --dry-run

Common Tasks

Inspect a package without changing your repo:

nodus info owner/repo
nodus info ./vendor/playbook
nodus info installed_alias

See what can be updated:

nodus outdated

Update dependencies and rewrite managed files:

nodus update

Rebuild managed files from what is already recorded:

nodus sync

Use these in CI:

nodus sync --locked
nodus sync --frozen

Remove a dependency:

nodus remove nodus

Check that your manifest, lockfile, store, and managed files are consistent:

nodus doctor

Generate shell completions:

nodus completion bash
nodus completion zsh
nodus completion fish

Advanced

Supported platforms:

• macOS (x86_64, arm64)
• Linux (x86_64, arm64/aarch64)
• Windows (x86_64)

By default, Nodus stores shared mirrors, checkouts, and snapshots here:

macOS:   ~/Library/Application Support/nodus/
Linux:   ~/.local/state/nodus/              (or $XDG_STATE_HOME/nodus/)
Windows: %LOCALAPPDATA%\nodus\

Override that location for any command with --store-path <path>.

Install a specific release with the installer script:

curl -fsSL https://raw.githubusercontent.com/WendellXY/nodus/main/install.sh | bash -s -- --version v0.1.0

When To Use sync vs update

Use nodus sync when you want Nodus to make the repo match your current manifest and lockfile.

Use nodus update when you want Nodus to look for newer allowed versions first, then sync to those newer results.

Use nodus sync --locked in CI when the lockfile must not change.

Use nodus sync --frozen when installs must use the exact revisions already recorded in nodus.lock.

Adapters

Nodus writes outputs only for the adapters your repo uses.

Supported adapters today:

• agents
• claude
• codex
• cursor
• opencode

You can choose adapters explicitly with --adapter, persist them in nodus.toml, or let Nodus detect them from existing repo roots such as .codex/ or .claude/.

Manifest

The smallest useful consumer manifest looks like this:

[adapters]
enabled = ["codex"]

[dependencies]
nodus = { github = "WendellXY/nodus", tag = "v0.3.2" }

Common dependency forms:

[dependencies]
playbook = { path = "vendor/playbook" }
tooling = { github = "owner/tooling", version = "^1.2.0" }
shared = { github = "owner/shared", tag = "v1.4.0", components = ["skills"] }

[dev-dependencies]
internal = { path = "vendor/internal" }

Direct dependencies can also map files or directories into the consuming repo:

[dependencies.shared]
path = "vendor/shared"

[[dependencies.shared.managed]]
source = "prompts/review.md"
target = ".github/prompts/review.md"

For a fuller example, see examples/nodus.toml.

Package Layout

Nodus discovers package content from these conventional paths:

• skills/<id>/SKILL.md
• agents/<id>.md
• rules/<id>.*
• commands/<id>.md

Packages can also declare:

• content_roots to publish additional folders
• publish_root = true to emit the root package itself
• capabilities for privileged behavior such as high-sensitivity actions

If a package declares high sensitivity capabilities, install or update with:

nodus sync --allow-high-sensitivity
nodus update --allow-high-sensitivity

Relay

nodus relay is for package maintainers who edit generated runtime files in a consumer repo and want to copy those edits back into the source checkout.

nodus relay nodus --repo-path ../nodus
nodus relay nodus --watch

This is an advanced workflow. Most users only need add, info, outdated, update, sync, remove, and doctor.

Why Teams Use Nodus

• one command to add repo-scoped AI tooling
• exact revisions locked in nodus.lock
• generated files stay managed and pruneable
• unmanaged files are never overwritten
• mirrors, checkouts, and snapshots are shared across repos

Contributing

See CONTRIBUTING.md for local development and release checks.

License

Licensed under Apache-2.0.