Project files and targets¶
Source of truth¶
| Path | Commit? | Purpose |
|---|---|---|
aru.toml |
Yes | Human-maintained sources, package requirements, selectors, and targets |
aru.lock |
Yes | Exact Git commits, MCP metadata, source digests, projections, and portable ownership baseline |
AGENTS.md, **/AGENTS.md |
Yes | User-owned, directory-scoped instruction sources |
.aru/cache/ |
No | Immutable, content-addressed Git checkouts |
.aru/state.toml |
No | Local deployment mode and last-applied ownership digests |
.aru/transaction.toml |
No | Crash-recovery journal, present only during interrupted operations |
aru init adds .aru/ to .gitignore. Generated target projections are not ignored automatically because each team decides whether to commit them.
For byte-level persisted-format details, see docs/formats.md on GitHub.
Managed projections¶
Depending on configured resources and targets, aru may reconcile:
CLAUDE.mdand.claude/rules/aru/**;.github/copilot-instructions.mdand.github/instructions/aru/**;- target skill directories listed in the skill target registry, including
.agents/skills/**,.claude/skills/**,.github/skills/**,.pi/skills/**, and.opencode/skills/**; .codex/config.toml,.mcp.json,.github/mcp.json, andopencode.json.
Aru owns only the entries or marker blocks it created. Unrelated configuration and unmanaged content remain outside its authority.
Target capabilities¶
| Capability | Agents | Codex | Claude Code | Copilot CLI | pi | OpenCode | Skill-only targets |
|---|---|---|---|---|---|---|---|
Directory AGENTS.md |
Native | Native | Sibling import | Root/path projection | Native | Native | No |
| Explicit instruction globs | No | No | Path rules | Path rules | No | No | No |
| Project skills | .agents/skills/ |
.agents/skills/ |
.claude/skills/ |
.github/skills/ |
.pi/skills/ |
.opencode/skills/ |
Registry-defined |
| stdio MCP | No | Yes | Yes | Yes | No | Yes | No |
| Streamable HTTP MCP | No | Yes | Yes | Yes | No | Yes | No |
| Environment-backed HTTP auth/headers | No | Yes | Yes | Yes | No | Yes | No |
Aru rejects configurations that a selected target cannot represent rather than silently broadening or dropping behavior.
Change targets¶
The six instruction-capable targets are agents, codex, claude, copilot, pi, and opencode.
Additional canonical targets support project skills only.
Use the available-target listing for the complete version-specific registry.
aru target list
aru target list --available
aru target add claude
aru target add kiro-cli
aru target remove codex
aru target set codex claude
CLI aliases normalize to canonical names before aru.toml and aru.lock are written.
Global home-directory skill installation is not supported.
addperforms a set union.removeperforms a set subtraction.setreplaces the complete set atomically.- At least one target must remain.
Target mutations resolve the complete result before atomically updating manifest, lock, ownership state, and owned paths. They preserve compatible locked package versions and support --dry-run.