Aracne

Give a coding agent a map of your codebase instead of a filesystem.

Website  ·  Documentation

Aracne scans a source tree and builds a topology: a directed graph of every package,
file, function, method, class/struct, interface, named type, variable and dependency, plus
the edges between them — who calls whom, which type implements which interface, what
imports what. It stores that graph in SQLite next to your code and keeps it current as
files change.

Then it answers questions from the graph instead of from raw text.

When an agent runs head -40 server.go, Aracne returns those forty lines framed by the
declaration they sit inside and followed by a # CONTEXT: block naming only the
resources those lines actually mention — each with a one-line description. The agent gets
the code plus the map around it, and stops paying for the three re-reads it would have
needed to work out where it landed.

Install

go install github.com/Rhuan-Marques/aracne/cmd/arac@latest

Or grab a binary from Releases. Two
builds are published:

Building from source needs gcc — the JavaScript, TypeScript, Rust and Java scanners are
tree-sitter, so CGO is required. SQLite is pure Go. See
CONTRIBUTING.md.

Scanning Python additionally needs a python3 (or python) on PATH at run time: that
scanner drives the interpreter's own parser rather than a grammar, so without one a Python
project simply yields no topology. Every other language is self-contained in the binary.

Quickstart

cd your-project
arac init

That is the whole setup. arac init is an interactive, full-screen flow that asks the six
questions a project actually has to answer — which harness, how the agent should reach your
code, who writes the descriptions and with which model, whether to describe the repository now
or lazily as you read, and how much the generated contract should say. It then saves them to
.aracne/config.json, scans the project, and writes the integration for your harness: the
contract block in CLAUDE.md/AGENTS.md, the hooks, and the config. From then on your
agent's ordinary grep and cat are answered from the topology.

Answer with the arrow keys and Enter; Escape cancels without writing anything. It needs a
terminal — in a pipe or in CI, use arac setup, which writes the same files from whatever
.aracne/config.json already says and asks nothing:

arac setup --claude      # or --opencode, or neither for both

Re-run arac setup after editing the config by hand. It reads mode and never writes it.

You can drive it yourself too:

arac read internal/server.Handler       # a resource, with its context
arac grep "retry"                       # searches names, descriptions AND contents
arac resource list --kind interface
arac warnings list                      # what drifted since the last scan
arac scanner run                        # keep the topology current in the background
arac viz serve                          # the graph, in a browser (Full build)

Description generation is the one part that needs a model, and nothing is assumed about
which. arac init asks — an API key, a CLI you are already logged into, or nobody at all —
and writes the answer into .aracne/config.json, so it is asked once:

// .aracne/config.json, after answering
"descriptions": { "provider": "openai", "api_key_env": "OPENAI_API_KEY" }
"descriptions": { "provider": "cli", "cli_provider_command": "claude -p" }
"descriptions": { "lazy": false }   // "Manual": your harness writes them, on request

The Manual answer configures no describer and turns the read-path fill off. Nothing is
spent until you run /descriptions-generate in Claude Code or OpenCode, which describes the
repository with that harness's own sub-agents — on the subscription you already pay for.

The CLI answer needs no API key at all — it spends the subscription behind a tool you already
use. Descriptions are also generated lazily, as a read or a search is about to show a node, so
a repo warms up as you work in it.

Everything else — scanning, reading, grepping, the visualizer — needs no key.
configuration.md has the whole story.

The four modes

Aracne's whole shape is one config key, mode, because how the agent reaches the topology
should be one decision rather than five independent switches:

Shell grep is answered by Aracne in all four, and edits re-sync the graph in all four.
See docs/modes.md.

Documentation

Full documentation lives at aracne-ai.lat/docs.html;
the project site is aracne-ai.lat. In-repo:

Next up

Uniting nodes into functionalities an agent can generate, maintain, and grep for
directly.

License

Apache-2.0. See NOTICE for third-party attribution.