Docs / Quickstart

From your first review to tests you keep.

The CLI workflow, with its costs and boundaries visible.

npm install -g @arnx-dev/arnx

This guide covers arnx 0.1.0. The release documentation is canonical for your installed version.

1. Prepare your environment

• A Git repository and a change whose intended behavior you can judge.
• Docker installed and running, with permission to create containers and build images.
• Node.js 20 or later for the npm package. Standalone binaries do not need Node.
• macOS or Linux. On Windows, use WSL 2 with Docker Desktop’s WSL integration.
• A supported model-provider API key with provider billing enabled for BYOM, or an arnx Cloud account.

Supported test runners: Python with pytest; JavaScript / TypeScript with vitest, jest, node:test or bun; Rust with cargo-nextest (early). Single packages and multi-project repositories are supported, but setup is not guaranteed for every framework or dependency.

More languages are planned. Want to see more here? ↗

Rust is early and the least-tested runner. First setup compiles dependencies and test targets into the Docker image. It can take minutes on a small crate, much longer on a large workspace, and several GB of disk space. Generated integration tests exercise the crate’s public API. Try it, have fun, and open an issue with what worked or broke.

2. Bring your own keys, or use Cloud

Bring your own supported provider keys, or let arnx Cloud manage model access.

BYOM: your provider keys

The default model configuration uses Anthropic. Set ANTHROPIC_API_KEY in your shell or secret manager; do not commit it. OpenAI roles use OPENAI_API_KEY. arnx init writes model choices and budgets in .arnx/config.toml. Review them before starting paid work.

Built-in provider support includes Anthropic Messages and OpenAI Responses. Have a favorite compatible endpoint? Try it out! Custom endpoints need configuration and testing. We’d love to hear what works, what breaks, and what you want to try next. Share your experiments on GitHub ↗

Open source means you can make it yours. Swap models, mix providers, or edit src/prompts.ts and rebuild with your own prompts. Have fun! The development guide explains how to build your version.

arnx cloud

If you don’t want to manage multiple providers and API keys, use our arnx Cloud. New accounts start with $5 in Cloud credit. With the CLI installed, run the commands for your project from its repository directory.

# New project
arnx init --cloud
arnx login

# Switch an initialized project to Cloud
arnx cloud on --yes
arnx login

--yes records your consent to send code to arnx Cloud without an interactive prompt. Omit it to read and answer the prompt. arnx init --cloud selects Cloud but leaves consent to the first command that sends code, normally arnx setup.

arnx login starts a GitHub device sign-in in your browser; complete it yourself. The CLI stores the token locally in ~/.config/arnx/credentials.json.

arnx credits
arnx doctor

arnx credits shows your balance and top-up link. See credit packs and top-up availability. arnx doctor reports which models are active and checks your environment. Tool calls, Docker tests, the before/after check, and report generation run on your machine. arnx cloud receives the diff, the files the agent reads, the tests it writes and their output, then passes them to its model providers. Use arnx cloud off to switch back to your own keys. arnx logout removes the local sign-in token.

3. Let your favorite coding agent handle it

Don’t want to handle reviews in the terminal? No worries. Your favorite coding agent can take the wheel. arnx was built for that! Install the arnx skill so Claude Code and other agents that read Agent Skills can review and fix code after finishing a change.

arnx skill install

This writes .agents/skills/arnx/ and .claude/skills/arnx/, including the skill’s references. Commit these directories to share the workflow with your team. Alternatively, arnx skill install --user installs them under your home directory for use across repositories.

An identical installed copy is left unchanged. To replace an older or edited copy, inspect your changes first, then use arnx skill install --force (add --user for the user-wide copy).

The skill instructs the agent to explain the review budget, run one review per finished change, fix code behind confirmed findings, and verify fixes with arnx check --review before checking accepted regression tests. It reports unresolved findings and questions back to you. Initialization, sign-in, consent, environment approval, triage, and arnx accept remain yours to perform; the skill instructs the agent never to edit accepted tests.

4. Run the workflow

The first command that sends code, normally arnx setup, asks for consent per repository and destination. Read it before approving. In non-interactive sessions, record explicit consent with arnx consent --yes (add --cloud for Cloud).

For BYOM, follow the sequence below. If you already initialized with Cloud or BYOM above, start at arnx setup. Run commands individually and inspect each result. If you use the skill, complete arnx setup yourself before handing a change to your agent.

arnx init
arnx setup
arnx review
arnx triage
arnx accept
arnx prompt
# Make and inspect the product-code fix, then:
arnx check

1. Setup: inspect the proposed Docker images, dependency-install commands, services, test commands, and excluded paths before approval. Image builds have network access; test runs have no external network, or an internal network for configured services. Docker shares the host kernel and is not a guarantee against malicious code.
2. Review: on a branch, the default includes commits since its base plus tracked uncommitted changes. Use arnx review --range A..B for an explicit span. On the default branch, it reviews tracked uncommitted work, or the last commit when clean.
3. Accept: replace <id> with the review ID, or omit it for the latest review. Read the generated tests and use arnx triage to validate marks; some findings arrive pre-marked real. Acceptance can call a model to turn your answers into tests. arnx accept --no-answers skips that step.
4. Check: fix production code, then rerun accepted tests with arnx check. No model inference is needed. Local Docker execution still consumes resources. Review and commit the fix, tests, and acceptance record.

Untracked files are excluded from setup and review by default in repositories with commits. --untracked or [review] untracked = true includes them; --no-untracked overrides the setting. Exception: with no commits yet, non-ignored files form the initial change. Inspect .arnxignore and the reported scope before sending code. Secret filtering is not exhaustive.

5. Keep the useful tests

arnx accept <id> keeps tests for findings marked real, then runs the accepted tests so you can see what still fails. Fix the code and run arnx check until they pass. Acceptance does not change your product code or commit anything.

Reviews live in .arnx/reviews/<id>/. Accepted tests normally live under each project’s tests/arnx/r<id>/. With the default setting, TypeScript uses __tests__/arnx/r<id>/; Rust places integration tests at tests/arnx_<id>_<name>.rs. Check [review] accepted_tests_dir in .arnx/config.toml for overrides.

Once arnx check passes, review and commit the fix, accepted tests, and .arnx/accepted-tests.json together. Keep the approved .arnx/config.toml, .arnx/review.yaml, and .arnx/.gitignore in version control too. The tests can then guard against the same bugs in your own test runner.

Review artifacts, run/setup files, and usage logs stay local and are ignored by Git. So does .arnx/precision.jsonl, your log of review marks. arnx init includes its ignore rule; arnx accept adds the rule to an older .arnx/.gitignore when missing. Ignore rules do not untrack files already in Git.

Accepted tests are pinned by their hashes in .arnx/accepted-tests.json. If a test or its record changes unexpectedly, arnx check stops with exit 4. arnx accept --again <id> restores the review’s tests, overwriting edits. For an intentional change you have reviewed, arnx accept --keep-edits records the current tests.

Costs and billing

With your own keys, you pay providers directly. Setup, review, and answer-to-test generation can incur model costs. Review your configured budgets; cost varies with model, change size, retries, and environment complexity. The CLI reports usage and writes .arnx/usage.jsonl. Reported case-study costs are observations, not prices or promises.

Expect a few cents to a few dollars per review. Our own reviews ranged from $0.17 to $3.19. Set review_usd under [budget] to control spending (default $3.00); the review stops writing tests when it reaches the cap and reports that it did.

arnx check and arnx check --review do not call models. Start with $5 in Cloud credit. How Cloud credit is billed.

Common failures

Cloud needs sign-in, consent, or credits

Run arnx login for missing or expired authentication. For missing Cloud consent, run arnx consent --cloud, or arnx consent --cloud --yes to explicitly agree without a prompt. Check arnx credits if your balance cannot cover a review. arnx next names the next step.

Docker or a provider key is missing

Run arnx doctor. Start Docker, check daemon permissions, and verify the configured key variable without posting its value.

Image build or dependency download fails

Read the setup log and proposed commands. Check registry connectivity and project dependency versions. Image builds need network access.

Setup cannot establish a working suite

Check the test command, fixtures, service readiness, and excluded projects. Do not treat an unapproved or incomplete environment as a clean review. arnx next reports the current state.

A review is interrupted

Inspect its report and use arnx review --resume when appropriate. An incomplete run is not evidence that the change has no bugs.

Check says a test changed

Exit 4 indicates an edited or missing accepted file or record. Restore unintended changes. Use arnx accept --keep-edits only after deliberately reviewing a test change.

Nothing was accepted

arnx check exits 3 when there are no accepted tests. Validate findings and run accept first.

Review exit codes: 0 no confirmed findings, 1 confirmed findings, 2 incomplete, 3 setup needed. Check exit codes: 0 passed, 1 failed, 2 incomplete reporting, 3 nothing accepted, 4 accepted-test integrity changed. A 0 is not a correctness guarantee.

Report a reproducible issue with the version, OS, runner, command, expected behavior, and sanitized output. Report security issues privately.