aru

Keep coding-agent instructions, skills, and MCP servers in sync across your project.

Aru gives your team one project manifest, one reproducible lockfile, and safe projections for every supported coding agent.

Documentation · Getting started · Command reference · Source

[!WARNING] Aru is under active development. Features, behavior, and file formats may change before 1.0.

Why aru?

Projects often repeat the same setup for Codex, Claude Code, GitHub Copilot, pi, OpenCode, and other agents.

Aru lets you declare that setup once:

• Keep existing AGENTS.md files as the canonical instructions.
• Install Agent Skills from Git repositories.
• Configure MCP servers without storing secret values.
• Reuse native aru packages that bundle instructions, skills, and trusted MCP declarations.
• Resolve selected skills and safe MCP from Agent Plugins, OpenAI plugins, and Gemini extensions.
• Pin exact revisions and projections in aru.lock.
• Detect drift and unmanaged content before replacing anything.

Aru supports full project adapters plus project-scoped skill-only targets.

Run aru target list --available for every canonical target, project skill path, capability, and accepted alias. Aliases such as claude-code, gemini-cli, and kiro-cli normalize to short canonical names before persistence.

Install

Aru requires a system git executable.

macOS and Linux

The recommended installer downloads a prebuilt, checksum-verified binary to ~/.local/bin and does not require Rust:

curl -LsSf https://raw.githubusercontent.com/narumiruna/aru/main/scripts/install.sh | sh

You can use wget instead:

wget -qO- https://raw.githubusercontent.com/narumiruna/aru/main/scripts/install.sh | sh

Windows PowerShell

The Windows installer places aru.exe in ~/.local/bin:

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/narumiruna/aru/main/scripts/install.ps1 | iex"

The standalone installers support x86-64 Linux, Intel and Apple Silicon macOS, and x86-64 Windows.

uv

The PyPI distribution is named arust because aru was already taken, but it installs the aru command:

uv tool install arust

Prebuilt wheels support x86-64 glibc Linux and Apple Silicon macOS.

Cargo

Install from crates.io with a Rust toolchain:

cargo install aru --locked

Verify the installation:

aru --version
aru --help

Quick start

The following workflow initializes a project for Codex and Claude Code, adopts existing instructions, installs a skill, and verifies the result.

1. Initialize your project

Run this command from the project root:

aru init --target codex --target claude

Initialization creates:

• aru.toml, which contains the setup your team maintains;
• aru.lock, which pins the exact resolved result;
• .aru/, which contains local cache, ownership, and recovery state.

Aru does not create or modify .gitignore. Add .aru/ to your ignore rules yourself.

To initialize another existing directory, pass its path:

aru init ../my-project --target codex

2. Adopt existing instructions

Specify each existing AGENTS.md file explicitly and preview the result:

aru instruction add AGENTS.md src/api/AGENTS.md --dry-run

Apply the result after reviewing the plan:

aru instruction add AGENTS.md src/api/AGENTS.md

Aru accepts exact project-relative AGENTS.md paths, keeps each source in place, and creates only the files required by your selected targets.

Configure glob selectors directly in aru.toml when needed.

If a destination such as CLAUDE.md already contains unmanaged content, aru stops instead of overwriting it.

Use --merge only after reviewing the collision:

aru instruction add AGENTS.md src/api/AGENTS.md --merge

[!CAUTION] --force destructively takes over colliding unmanaged content. A later removal cannot restore that content.

3. Add an Agent Skill

Choose a skill interactively:

aru skill add narumiruna/skills

For scripts and CI, select exports explicitly:

aru skill add narumiruna/skills --skill writing-plans

Aru resolves the Git revision, records it in aru.lock, and projects the skill to each compatible target.

4. Verify the project

Replay the committed lock without changing its resolutions:

aru sync --locked

Check that the lock and all managed target files are current without changing project or target content:

aru sync --check

5. Commit the reproducible state

Commit aru.toml and aru.lock.

Your team may also commit generated target files if that matches the repository's policy.

Do not commit .aru/.

The everyday workflow

Most aru commands follow the same pattern:

1. Preview risky or unfamiliar changes with --dry-run. Previews may create private per-user lock metadata outside the project, but do not change project or target files.
2. Apply the command.
3. Review aru.toml, aru.lock, and projected target files.
4. Run aru sync --check.
5. Commit the intended files.

Add, remove, update, and target commands normally update the manifest, lockfile, and target projections together.

Use --no-sync when you intentionally want to update only aru.toml and aru.lock, then run aru sync later.

Interactive guidance

In a terminal, aru helps fill omitted selections:

• aru init and aru target add/remove/set open target menus.
• aru skill add owner/repository asks for Project or Global scope, targets, and skills.
• Managed aru add, aru plugin add, and aru mcp add offer configured target choices when --target is omitted.
• Bare remove and resource remove commands offer configured items; bare update commands offer a multi-select menu with all eligible items checked.
• aru instruction add prompts for an exact project-relative AGENTS.md path.

Use arrow keys to move, space to toggle multi-select items, typing to filter menus, Enter to accept, and Esc to cancel. Pass --no-interactive to disable all prompts. Without prompts, existing defaults remain: project scope, configured managed targets, and update-all. Required missing selections produce an actionable error. Inspection, sync, lock, packaging, and self-update commands do not gain prompts. Source identifiers, MCP configuration, and trust flags remain explicit.

Common tasks

Manage instructions

Add root and nested AGENTS.md files explicitly:

aru instruction add AGENTS.md src/api/AGENTS.md --dry-run
aru instruction add AGENTS.md src/api/AGENTS.md

List configured instruction selectors:

aru instruction list

Remove a selector without deleting the canonical instruction file:

aru instruction remove AGENTS.md --dry-run
aru instruction remove AGENTS.md

For custom paths, globs, and target-specific rules, see the instructions guide.

Manage Agent Skills

aru skill list
aru skill add owner/repository --skill review
aru skill add owner/repository --all
aru skill add --target codex owner/repository --all # works without aru init
aru skill add --global --target codex owner/repository --skill review
aru skill update --dry-run
aru skill update
aru skill remove owner/repository --skill review
aru skill remove owner/repository

A bare skill add SOURCE in a terminal asks for installation scope, targets, and skills. Use --scope project to skip the scope menu, or -g, --global, or --scope global for user-level installation.

Project scope uses the initialized aru project when one is found; otherwise it performs a one-time installation in the current directory. Pass --target explicitly or choose from the menu. Managed installations offer only configured targets. Global scope always performs a standalone installation, even inside an initialized project, without changing its manifest, lockfile, or targets. Relative sources resolve from the current directory or explicit --project directory. Destinations inside managed projects remain rejected to protect managed content. Standalone installation leaves no manifest, lockfile, ownership state, or project cache.

Non-interactive environments must use --target in standalone mode and select skills with --skill, --all, or --path.

Aru discovers skills from SKILL.md files at the repository root or in nested directories within its discovery limits. When a source repository has a valid aru.lock, automatic discovery ignores each unchanged locked skill under its corresponding hidden target projection directory, such as .agents/skills/ or .pi/skills/; drifted content remains discoverable, and an explicit --path still selects one of these directories.

Each skill's name must match the directory containing its SKILL.md, or the repository name for a root skill.

See the Agent Skills guide for revision pinning, target selection, and non-standard layouts.

Manage MCP servers

Add an HTTPS MCP endpoint while storing only the environment variable name for its token:

aru mcp add \
  --url https://docs.example.com/mcp \
  --name docs \
  --bearer-token-env DOCS_MCP_TOKEN

Without an aru.toml in the current directory or an ancestor, pass a target to install the entry once without creating aru project state:

aru mcp add \
  --target codex \
  --url https://docs.example.com/mcp \
  --name docs

Omitting --target in an interactive standalone command opens a target selector for Codex, Claude Code, Copilot CLI, and OpenCode. Standalone installation merges the named entry into native project config, preserves unrelated entries, and requires --force to replace an existing same-name entry. The resulting entry is not managed by mcp update, mcp remove, or sync.

List, update, or remove managed MCP declarations:

aru mcp list
aru mcp update --dry-run
aru mcp update context
aru mcp remove docs

Aru also supports Registry packages and direct stdio argv.

It validates direct commands but never executes them during add, lock, or sync.

Project MCP is supported for Codex, Claude Code, GitHub Copilot CLI, and OpenCode.

See the MCP guide for all source types and target capabilities.

Manage native aru packages

A native package can bundle reusable instructions, skills, trusted MCP declarations, and package dependencies.

aru add owner/agent-kit
aru add owner/agent-kit --version '^1.2'
aru update --dry-run
aru update
aru remove owner/agent-kit

Package-provided MCP servers are denied by default and require an explicit trust decision.

See the native packages guide for package authoring, trust, and dependency behavior.

Manage plugin dependencies

Inspect and import portable plugin resources without installing or executing plugin code:

aru plugin info owner/review-tools
aru plugin add owner/review-tools --component skills
aru plugin add owner/review-tools --mcp docs --trust-mcp docs
aru plugin update --dry-run
aru plugin list
aru plugin remove review-tools

Whole-plugin intent fails when active native capabilities cannot be represented safely.

Explicit --component, --skill, and --mcp selectors authorize a compatible subset.

See the plugin dependencies guide for detection, safe MCP limits, trust, and lock behavior.

Change project targets

aru target list
aru target list --available
aru target add copilot
aru target add kiro-cli       # persists canonical target "kiro"
aru target remove claude
aru target set codex claude

Skill-only targets receive skills but not instructions or MCP servers. Managed project destinations are project-relative; standalone aru skill add --global uses target-native user directories instead. At least one target must remain.

Use target set when replacing the only configured target.

Understand locking and synchronization

aru.toml describes what the project wants.

aru.lock records the exact Git revisions, metadata, content digests, and target projections needed to reproduce it.

Use --offline to disable remote Git and Registry access.

Use --frozen for the equivalent of --locked --offline.

Read the lock and sync guide for detailed behavior.

Safety model

Aru is designed to fail closed.

Before writing, it validates the complete operation and rejects unsupported, ambiguous, or unsafe inputs.

It also:

• preserves drifted or unowned content for review;
• keeps Git and MCP commands as argument arrays instead of shell-expanding them;
• never executes configured direct MCP commands;
• stores secret environment variable names or placeholders, never secret values;
• applies multi-file changes through atomic transactions;
• records durable recovery information for interrupted operations.

If an operation is interrupted, run a mutating aru command such as aru sync again.

Aru will attempt digest-gated recovery before starting new work.

Read the safety and recovery guide before using destructive takeover or repairing interrupted transactions manually.

Useful inspection commands

These commands inspect the project without changing managed state:

aru sync --check
aru audit
aru tree
aru info PACKAGE
aru plugin info SOURCE
aru metadata --format-version 1
aru metadata --format-version 2

Run aru COMMAND --help for command-specific options.

The complete command reference lists every command and flag.

Updating aru

Standalone installations can update themselves:

aru self update

Update package-manager installations through the same package manager:

uv tool upgrade arust
cargo install aru --locked

Development

Install from a source checkout:

cargo install --path .

Run the CI-equivalent checks:

cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-targets --all-features

Serve or build the documentation with its locked toolchain:

just docs-serve
just docs-build

Release maintainers should follow docs/releasing.md.

Aru is available under the MIT License.