ARNO — Agent Repository Navigation & Operations

The IDE for agents

ARNO gives coding agents what an IDE gives you, served over MCP. Read by symbol, edit against a known revision, get the compiler's diagnostics back with the edit, validate with the repository's own commands, see what changed, and revert to a checkpoint — each step one tool call, none of it through the shell.

Symbol-aware reading is how ARNO finds its way around; the transaction is what it is for. Where the shell is still the better tool, use it — the question ARNO has to answer is whether an agent gets more done, at acceptable cost, with it than without (docs/benchmark.md).

Half the tokens, more issues fixed. Claude Code on 12 real closed issues from cobra (Go), ky (TypeScript), requests (Python) and ripgrep (Rust), judged by each upstream fix's own hidden tests:

Not just a shorter tool list: against a shell trimmed to Bash, Read, Edit and Write, ARNO still used 18–25% fewer tokens and fewer turns, in two separate runs. Sonnet 5, one run per task, four languages — results and caveats · how to set it up.

Status: 0.0.11 shipped as Jade; 0.0.12 is the first release called ARNO — early, usable, and looking for feedback. Testing it? Start with the tester guide.

curl -fsSL https://raw.githubusercontent.com/julianbei/arno/main/install.sh | sh

For macOS and Linux — Windows isn't supported (here's why, and where to upvote). Run it again to update. Other ways to install.

Table of contents

• Trying ARNO: a guide for testers
• Why ARNO exists
• Install
• Configure your MCP client
• Use it in a container
• The tools
• Repository commands
• Language support
• Design principles
• When the shell is still the right tool
• What ARNO does not do yet
• Stability and versioning
• Telemetry
• Reporting problems
• Development

Trying ARNO: a guide for testers

Thanks for testing. Half an hour gets you set up; the useful part is a week or two of your normal work with it switched on, and then telling us how it went — including if you turned it off.

1. Install ARNO and your language servers

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/julianbei/arno/main/install.sh | sh

Windows isn't supported, sorry! If you'd like it to be, please 👍 issue #2 or tell us there why it matters to you. (WSL 2 runs Linux, so the Linux build may work there, but we don't test it or take bug reports for it.)

The script picks the build for your OS and CPU, checks it against the release's checksums and installs it to /usr/local/bin, or ~/.local/bin when that is not writable — no sudo, no Go toolchain. If that directory is not on PATH, it offers to add it to your shell profile, and it prints the absolute path to use as command in your MCP client config. On a first install it then opens arno-mcp install, a menu that installs the language servers you pick, or shows how to install them by hand; Enter skips it, and you can run it again any time. Run the same command again to update — ARNO tells you when a new release is out (see Update check). (Prefer Go? go install github.com/julianbei/arno/cmd/arno-mcp@latest works too.) ARNO reads structure in every language with nothing else installed; exact references, cross-file rename and type errors on edit need the language's server — arno-mcp install installs these for you, or by hand:

A missing server is never an error: ARNO says which answers are approximate.

2. Point your agent at a real repository

For Claude Code, put this in .mcp.json at the root of the repository you work in (other hosts: Codex CLI, goose, OpenCode):

{
  "mcpServers": {
    "arno": {
      "type": "stdio",
      "command": "arno-mcp",
      "args": ["--root", "/absolute/path/to/the/repo", "--tools", "core"],
      "alwaysLoad": true
    }
  }
}

That keeps Claude Code's own tools too. For the clearest signal, run some sessions with ARNO in place of them: claude --tools "" with the same config (why and trade-offs). Restart or reconnect the client (/mcp) after installing or upgrading ARNO.

3. Check it came up

Ask the agent: "call arno.capabilities". You should see your languages, each with server … (not started) or no server (… not installed), plus the build and test commands ARNO found (mvn, gradle, sbt, go test). If a server you installed shows as not installed, that is a bug report.

4. What to try

Work as you normally would. If you want a checklist for the first sessions:

• Find and follow code: "where is X declared, and who calls it?" — find, references.
• Rename across files: a method or class used in several files — rename (exact with gopls, jdtls or metals running).
• A change in several places at once: "change the signature and update the callers, then check it builds" — apply with check.
• Run the tests that matter: run_tests with a file or test name, or apply with check: "impact".
• Repeatable commands: have the agent declare_command something you run often (./gradlew :core:test, sbt "testOnly *ParserSpec"); later sessions reuse it from .arno/commands.json.
• Undo: checkpoint before something risky, revert if it goes wrong.

5. Tell us how it went

The templates ask for the output of arno.capabilities and, optionally, arno.telemetry. Neither contains source code; telemetry is local only and records no arguments or response text, so both are safe to paste from a private repository.

Known rough edges on the JVM: no formatter runs for Java or Scala files; large Gradle builds can make jdtls's first answer much slower than 8.5s; Kotlin has no support yet.

Why ARNO exists

An agent that falls back to grep, sed and cat is operating outside any tooling you control. No revision tracking, no guardrails, no telemetry, no way to know what it did or why it chose to do it that way. Every shell fallback is a hole in your visibility.

You cannot fix that by telling the model not to use the shell. The model uses the shell because the shell is cheaper — fewer tokens, fewer round trips, more flexible. So the only durable fix is to make the structural tool the cheaper option, and then measure whether you succeeded.

That is the entire bet, and it is testable. On this repository's own benchmark, ARNO answers seven realistic engineering questions in 0.85x the tokens of the equivalent shell commands. It was 5.63x before responses became plain text instead of JSON — see docs/response-style.md for what changed and why.

The counter-measurement matters as much. One question asked against an unrelated repository came out at 1.36x — worse than the shell — because an ambiguous symbol name forced an extra disambiguation call. Seven scenarios at home and one away disagree, both are honest, and the second is the one that predicts outside use. The 0.0.4 pilot on four outside repositories answers it at a larger scale: used in place of Claude Code's built-in tools, ARNO solved 12 of 12 real issues with 51% fewer tokens, and 18–25% fewer than a shell trimmed to four tools (docs/benchmark-results.md). ARNO is not finished.