cargo-axi

cargo-axi gives coding agents a compact, structured view of the Rust Cargo workspace they are working in, then lets them run safe check or Clippy validation without forwarding arbitrary Cargo arguments.

Its normal output is TOON, so it is designed to be read by an agent or another structured tool rather than by a human-oriented terminal UI.

Install from this source checkout

Install the Cargo subcommand from a clone of this repository:

cargo install --locked --path .

Then, from a Rust package or workspace, start with:

cargo axi

After the public v0.1 release, install it from crates.io with:

cargo install --locked cargo-axi

The source repository is AG9898/cargo-axi.

Commands

# Orient in the current workspace.
cargo axi
cargo axi packages
cargo axi package api
cargo axi features api

# Validate through a small, declared Cargo argument surface.
cargo axi check --package api
cargo axi clippy --workspace

# See command-specific usage and allowed flags.
cargo axi check --help

Run cargo axi --help for the complete command list. Successful results and usage errors are TOON on standard output. A validation failure exits with status 1; invalid cargo axi arguments exit with status 2.

Safety boundaries

• Workspace views use cargo metadata --no-deps; they do not fetch or mutate the target workspace.
• check and clippy accept only documented package/workspace and feature flags. They do not pass arbitrary arguments through to Cargo.
• Validation uses --locked by default. Use --allow-lock-update only when a lockfile change is intentional.
• The tool does not edit source, manifests, dependencies, Git state, or arbitrary Cargo state.

Optional agent-session hooks

The default is an explicit, project-scoped integration that adds workspace context for Claude Code, Codex, or OpenCode:

cargo axi setup hooks install --app all --scope project
cargo axi setup hooks inspect --app all --scope project
cargo axi setup hooks remove --app all --scope project

Use --scope user only when a machine-wide installation is intended. Ordinary cargo axi commands never install or modify hooks.

The installed lifecycle integrations also preserve one compact, per-workspace summary for the next session: the ending time and the last check or clippy result (scope, status, duration, and error/warning totals). It is written under the user's XDG state directory using a hashed workspace key. It never reads or stores prompts, transcripts, source text, file lists, diagnostics, or the workspace path. Remove the current workspace's summary with:

cargo axi session clear

Development checks

cargo fmt --check
cargo test
cargo clippy --all-targets -- -D warnings
cargo package --allow-dirty

The bundled agent skill is at skills/cargo-axi/SKILL.md. Its command reference is checked against the CLI metadata by the test suite.

Contributing

Read CONTRIBUTING.md before proposing a change. It defines the supported Rust version, required local checks, and the v0.1 safety and output contract contributors must preserve.

License

This project is licensed under MIT.

Release status

The v0.1 implementation is ready for its first public release.