ARNO

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.14 shipped, the first release without the Jade names; 0.0.11 and earlier were Jade — 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.

ARNO's own development log (docs/feedback.md) records every time its author reached for bash instead, and why. The pattern it found was blunt: the fallbacks that survived longest each closed within two tasks of being *named in the log* — not when the tool shipped.

---

Install

With the install script

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

Downloads the latest release binary for your OS and CPU, verifies it against checksums.txt, and installs it without sudo to /usr/local/bin or ~/.local/bin. Run it again to update: a arno-mcp already on PATH is replaced where it is, and nothing is downloaded when it is already current. If the directory is not on PATH, it offers to add it to your shell profile (ARNO_ADD_TO_PATH=1 does it without asking) and prints the absolute path to use in your MCP client config. ARNO_VERSION pins a release tag; ARNO_INSTALL_DIR picks the directory. Read it first if you like: install.sh.

Windows isn't supported — see issue #2, and give it a 👍 if you'd like that to change.

Language servers: arno-mcp install

arno-mcp install                           # menu: pick what to install

arno-mcp install --list # what is installed, and how the rest would be arno-mcp install --servers go,java,scala # install these, no questions arno-mcp install --all # every missing server this machine can install

The menu lists each language server ARNO can use, whether it is installed, and the exact command it would run — go install for gopls, brew install jdtls, cs install metals, npm install -g for TypeScript and Pyright, rustup component add rust-analyzer, gem install ruby-lsp — and confirms before running anything. A server with no installer on the machine gets instructions for installing it by hand. The install script opens the menu after a first install; ARNO_SKIP_SETUP=1 skips it.

For an agent, or any script — there is no terminal to answer a menu, so the same steps come without questions:

# install ARNO and chosen serv