Aracne documentation

01Overview

The scan builds a topology and persists it to SQLite at .aracne/topology.db, next to your code, then keeps it current as files change. A read returns the declaration you asked for, framed by its signature and followed by a # CONTEXT: block naming only the resources those lines actually mention, each with a one-line description. A search also matches node names and stored descriptions, so a plain-English query finds code that never says the word.

What’s in it

• The topology engine for Go, Python, JavaScript, TypeScript, Rust and Java — full, incremental and hard scans.
• Description generation as a sweep (arac descriptions generate) or lazily on the read path, against Anthropic, OpenAI or DeepSeek — or a CLI you are already logged into, with no API key.
• Read, write and grep served from the topology — through the shell your agent already types, through arac read, or as MCP tools, depending on the mode.
• Harness integration for Claude Code and OpenCode — contract, hooks, plugins, sub-agents, slash commands and MCP config, all written by arac setup. CLAUDE.md, AGENTS.md and Aracne's own agent harness get one document, as long or as short as contract_verbosity says.
• The Viz menu — a local web visualizer with package, data-flow and custom views, neighborhood exploration, search and a source inspector. Full build
• Maintenance commands: arac setup, arac warnings list, arac check-updates, arac scanner run, arac disable, arac descriptions export|import.

02Install & the two builds

Aracne publishes two builds of the same engine. They differ in exactly one thing: whether the web visualizer is compiled in.

Install a release binary

Release assets are named arac-<goos>-<goarch> for the Full build and arac-<goos>-<goarch>-basic for Basic, with a SHA256SUMS alongside them. Published for linux/amd64, darwin/arm64 and windows/amd64; the Windows pair carries .exe (arac-windows-amd64.exe, arac-windows-amd64-basic.exe).

curl -LO https://github.com/Rhuan-Marques/aracne/releases/latest/download/arac-linux-amd64
chmod +x arac-linux-amd64 && sudo mv arac-linux-amd64 /usr/local/bin/arac
arac --version

Install with Go

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

go install produces the Full build.

Build from source

git clone https://github.com/Rhuan-Marques/aracne && cd aracne
make build         # Full  → bin/arac
make build-basic   # Basic → bin/arac-basic

03Quickstart

cd your-project

arac init

That is the whole setup. arac init will guide you through some more questions to get your setup, when it finishes, it's all good to go

04The topology

A topology is a set of resources (nodes) and connections (typed, directed edges). Multiple languages merge into one graph; the topology's language is then multi.

Resource kinds

Each resource carries an ID, that can be used to search for the resource. They also contain a Kind, a Name, a Language, a one-line Description, a Position and their free-form Properties (typed input/output, for example) and its Connections.

Edge types

Connection keys are shared vocabulary across the scanners, so a graph walk needs no per-language code. Go says uses_struct where Python says uses_class; both mean "this resource references that type".

Scan modes

What the scanners skip

• Dot directories, .git, .aracne, node_modules, vendor, __pycache__.
• Test and build artifacts: Go *_test.go, Python test_*.py, JS/TS *.test.* / *.spec.* / *.min.*.
• Anything matched by scan.ignore.
• Anything hidden by paths.
• Files over read.max_file_size.

The context block

A read returns source plus a # CONTEXT: section listing the neighbours those exact lines touch, each with its description. Under read.context_filter: "full" a # USED BY: section lists callers as well.

Under read.context_filter: "normal" neighbours with no description are omitted — which is what lazy descriptions fill in. Constants are exempt: a value shown is a description.

05Resource IDs

Every declaration has a stable ID. IDs are the addressing scheme for arac read, the read MCP tool, and — in the intercept_id mode — for ordinary shell read commands, which accept an ID wherever they accept a path.

Java carries signatures because it overloads, and it mints synthetic names for the awkward declaration forms: $anonN, $Local, Enum$CONST, constructors as <Owner>.<init>(<sig>), initializer blocks as <clinit>() / <instance-init>(), and record accessors as <Rec>.<comp>().

Search output and # CONTEXT: entries print the ID of every declaration they name.

06Descriptions

A description is one line of prose stored on a node in the topology database. It is the only thing grep can match that does not exist in the source text at all — so a plain-English query finds a node whose code never says the word.

Descriptions are generated three ways:

Comments

Any resources that already have comments on how they work are automatically converted, as long as they follow their character budgets.

The sweep

arac descriptions generate lists the undocumented resources of the targeted kinds, splits them into deterministic non-overlapping batches, and fans out descriptions-generation-executor sub-agents — one per batch, all in one concurrent wave. When the wave finishes it re-lists what is still undocumented (the database is the source of truth, not the executors' self-reports) and launches another wave, until none remain.

Kinds default to function, method, struct, interface and are set by descriptions.kinds or the --targets flag.

Lazy descriptions on by default

descriptions.lazy generates a missing description at the moment a read or a search is about to show it, rather than only in a sweep.

Who writes them

The sweep and the lazy fill read one provider block, on the descriptions section itself. arac init asks for it — an API key, or a CLI you are already logged into — or you can write the block by hand.

The model is set elsewhere — on the descriptions-generation-executor agent, which both the sweep and the lazy fill describe with:

{ "llm": { "<any>": { "agents": {
  "descriptions-generation-executor": { "model": "claude-haiku-4-5" }
} } } }

arac init asks for it and writes it under <any>, so one answer covers Claude Code, OpenCode and the lazy fill alike. It offers the chosen provider's cheap tier — claude-haiku-4-5, gpt-5.4-mini or deepseek-v4-flash — and leaving it unset is fine: a cheap tier is used anyway.

The three API providers read ANTHROPIC_API_KEY, OPENAI_API_KEY and DEEPSEEK_API_KEY unless api_key_env names another variable. Nothing else in Aracne needs a key.

Describing with the Claude CLI, no API key

provider: "cli" describes through a CLI you are already logged into, spending that subscription instead of an API key: Aracne runs a command, writes the batch to its stdin, and reads the descriptions off its stdout.

"descriptions": {
  "provider": "cli",
  "cli_provider_command": "claude -p"
}

That is the whole setup. claude must be on PATH and already logged in — running it once, interactively, is enough. Both entry points then use it:

arac descriptions generate    # the sweep, through `claude -p`
arac read internal/server.go  # a lazy fill, through the same command

Pin a model and cap the turns — the batch already carries every resource's source, so there is nothing for the CLI to go and fetch:

"cli_provider_command": "claude -p --model haiku --max-turns 1"

It does not have to be Claude. Any command that answers a prompt on stdout will do, such as "cli_provider_command": "codex exec".

One run, without touching the config

arac descriptions generate --cli describes the repository through a command for that run only, overriding whatever descriptions.provider says.

arac descriptions generate --cli "claude -p"     # a command you named
arac descriptions generate --cli "codex exec"    # any command works here too
arac descriptions generate --cli                 # the default, `claude -p` — asks first

Quote a command that has flags of its own: bare --cli and --cli <command> are the same flag, so --cli claude -p would read -p as one of Aracne's flags.

Character budgets

Descriptions have a per-kind budget, enforced on write: 120 characters for a function or method, 100 for a type, 80 for a variable. Rows written before the budget existed are grandfathered; arac descriptions clear --oversized is the explicit sweep for those, and arac descriptions generate --regen_oversized rewrites them instead of describing undocumented nodes.

Getting them out of the database

• arac descriptions export backs them up to an ID-independent JSONL sidecar (.aracne/descriptions.jsonl), and import restores them after a re-scan. Do this before a --hard scan, or before any change that re-mints IDs.

07Topology warnings

After an edit, Aracne can tell an agent that its change may have broken callers. Warnings are surfaced through arac warnings list and the warnings_list tool, and the post-call drift check reports the ones a write causes.

The last two are derived from current state, not remembered from an event, which is what lets them retire themselves: fix the caller and the warning disappears on the next scan.

interface_conflict is only raised where declaring an interface is a claim that can be wrong: Rust, Java, TypeScript, Python ABC. Go and Python Protocol are structural, so a type that does not satisfy an interface simply has no implements edge.

08The four modes

mode in .aracne/config.json is the one dial. It answers three questions at once — which tools exist, which shell commands Aracne answers, and what vocabulary the generated contract teaches — and every artifact arac setup writes derives from it.

It is question two of arac init, which shows each mode with what it means and an example of what it looks like. Editing the key by hand and re-running arac setup is the other way; arac setup only ever reads it.

It decides which capabilities the contract may name; contract_verbosity decides how much it says about them. See The injected contract.

Three things hold in every mode. Shell grep is answered by the annotated grep. Edits re-sync the topology. And arac read / arac grep work from the CLI regardless.

Which one to pick

• Start with the default. cli costs nothing per request and gives you the annotated grep, the edit sync and the contract.
• Use intercept_line_ranges if you want reads answered from the graph without teaching the model a new addressing scheme: every declaration is named by the exact lines it spans (src/parser.rs:940-1080), and reading an advertised span returns byte-for-byte what the resource read would have.
• Use intercept_id if you want IDs specifically — an ID cannot land mid-declaration and does not go stale when the file shifts.
• Use mcp on a harness where a real tool schema is worth more than a shell rewrite, or where you want blocked_tools to be able to refuse a native read.

grep, edit and write are not MCP tools in any mode — their shell forms are intercepted everywhere.

09The terminal surface

In the intercepting modes, the shell is the tool surface. The agent writes head -40 server.go and reads real stdout; a PreToolUse hook rewrites the call into arac cmd -- head -40 server.go, which answers it from the topology: the exact lines asked for, framed by the signature of whatever declaration they sit inside (with an elision marker for what was left out), plus a # CONTEXT: block restricted to the resources those lines actually mention.

A resource ID stands wherever a path does, so head -20 app.Flask is the first twenty lines of the class body.

What is modelled

What passes through, byte-identically

Anything Aracne does not model runs exactly as it would have, and the real binary's exit status is preserved.

• Any flag not modelled — head -c, tail -f, grep -o, sed substitutions.
• Readers that transform rather than window — nl, tac, xxd, od, hexdump, strings.
• An unindexed file, a missing database, or a file with no topology nodes.
• An over-budget answer — a read or a search past terminal.max_overserve times the bytes the real command would have printed.
• Anything the guard will not rewrite — across a pipe, a redirect, a heredoc, an &&, an env prefix or a wrapper; a mutation; or a command already rewritten once.

A search that found nothing exits 1, the way grep and rg do.

The guard, mode by mode

Where blocking applies, interception is tried first: a command Aracne can serve is answered rather than refused, however blocked_tools reads.

Freshness

Before every tool call the guard sees, it runs the scan.pre_tool scan, so the call is answered from a graph that matches the code on disk — including changes nothing in the session made, like a git checkout, a rebase or an editor save. Claude Code gets this from the PreToolUse guard hook; OpenCode gets it from arac-pre-tool-scan.js, installed unconditionally. Both read the same config key at call time, so scan.pre_tool: "none" disables it on both surfaces without re-running init.

The pre-call scan reports nothing. The warnings it finds are persisted and surface through warnings_list / arac warnings list.

10The MCP server

arac serve is a JSON-RPC 2.0 MCP server over stdio, supporting initialize, tools/list and tools/call. It is how Claude Code and OpenCode consume Aracne in mcp mode, configured in .mcp.json / opencode.json.

No API key is needed. The host platform brings its own model; the server only answers questions from the graph.

{
  "mcpServers": {
    "aracne": {
      "command": "arac",
      "args": ["serve", "--tool-profile", "main", "--harness", "claude_code"]
    }
  }
}

Tool profiles

--tool-profile and --harness together select which config-resolved tool set is exposed. A profile is an agent name: the server looks up llm.<harness>.agents.<name>.mcp_tools, falling back through llm.<any> and then the main agent.

--tool-profile main

The main agent's tools. What Claude Code is wired to.

--tool-profile all

Every servable tool. What OpenCode is wired to, because its permission block does the narrowing instead.

--tool-profile descriptions-generation-executor

Just read + update_description.

--harness claude_code

Default. Applies the claude_code overrides.

--harness opencode

Applies the opencode overrides.

Whatever a profile names, grep, edit and write are always dropped (they are shell-served in every mode), and nothing at all is served outside mcp mode.

11CLI reference

The binary is arac. Running it with no arguments prints the usage banner. The viz serve block is absent from the Basic build.

Scanning

arac scan
arac scan --all --verbose
arac scan -root ./services/api -output ./services/api/.aracne/topology.db

Reading & searching

arac read internal/topology/golang.GoManager
arac read internal/cli/read.go
arac read internal/cli.RunRead internal/cli.parseReadArgs
arac read --kind interface Shape

arac grep "retry"
arac grep --type go --glob 'internal/**' "WithFileLock"
arac grep -i --output-mode files_with_matches "deprecated"

arac resource list --kind interface
arac resource list Handler --kind struct --kind interface
arac resource list --no-description

The terminal surface

arac cmd -- head -40 internal/cli/guard.go
arac cmd -- cat internal/cli.RunGuard          # an ID stands where a path does
arac cmd -- grep -rn "retry" internal/
arac cmd -- xxd logo.png                       # passthrough, byte-identical

Descriptions

arac descriptions export
arac scan --hard
arac descriptions import --min-rate 0.9 --report /tmp/unmatched.jsonl

Mutating code

echo '{"file_path":"main.go","old_string":"foo","new_string":"bar"}' | arac edit

echo '{"edits":[
  {"file_path":"a.go","old_string":"x","new_string":"y"},
  {"file_path":"b.go","old_string":"p","new_string":"q"}
]}' | arac edit

echo '{"file_path":"internal/new.go","content":"package internal\n"}' | arac write

Index health & analysis

arac check-updates --json
# {"db":"...","root":"...","stale":true,"drifted":3,"added":[...],"modified":[...],"deleted":[...]}

Integration & servers

12MCP tool reference

Every tool name that can be referenced in .aracne/config.json is validated at load and init time, so a typo fails fast rather than silently disabling a tool.

Default tool sets

The tools in detail

13Harness integration

Two commands, split along one line: arac init asks, and arac setup writes. The wizard collects the answers, saves them, scans, and then runs the writer itself; every later re-render is arac setup alone.

Every artifact is generated from the mode key, with contract_verbosity deciding how much the contract says.

Setting a project up

arac init takes over the terminal and asks up to seven questions, one per screen, each option carrying an explanation and a worked example that redraws as the highlight moves. Arrow keys move, Enter selects, Esc cancels.

   ▄▀█ █▀█ ▄▀█ █▀▀ █▄░█ █▀▀
   █▀█ █▀▄ █▀█ █▄▄ █░▀█ ██▄

  How should the model reach your code?                                      2/7

  This is the one dial. It decides which tools exist, which shell commands
  aracne answers, and what the generated contract teaches. Shell `grep` is
  answered by aracne and edits re-sync the topology in all four.

  > cli                    No MCP tools. The contract points at `arac read
    mcp                    <id>`.
    intercept_id
    intercept_line_ranges  Shell reads run as themselves; the model is taught to
                           prefer resource IDs and reaches them through the
                           terminal.

                           The default, and the cheapest: nothing is added to
                           the tool schema of every request.

                             $ arac read internal/cli.RunSetup
                             internal/cli.RunSetup  (function)

  ↑/↓ move   ⏎ select   esc cancel

Every open question — the key's variable, the command, the model — offers a default on the first row and Other: on the second, where you type.

Claude Code

OpenCode

The injected contract

arac setup writes a block into CLAUDE.md / AGENTS.md explaining to the model how to use it. The contract is different per-mode.

contract_verbosity — how much it says

Two prompt lengths are available per mode, set by contract_verbosity.

Only high varies by language: how an ID is spelled, what a read returns, and how the graph models that language.

# Aracne

`.aracne/topology.db` holds a pre-analyzed graph of this repo: every function,
type, interface and variable, where it is declared, a one-line description, and
what it references.

`arac read <id> <id> ...` returns declarations with their source, their imports
and a `# CONTEXT:` list of what they touch AND what implements, subclasses or
uses them, each with its description. Several ids in one call.

**Reach for it the moment you want to know** where something is defined, who
calls or implements it, or what one declaration does inside a large file. Each
of those is `arac read <name>` -- not `grep -rn`, not `cat`, not `sed -n`, not
`find`. Open a whole file only for a config, an unsupported language, or when
you genuinely need all of it.

**The bare name is enough** -- any unique trailing part of an id resolves, and a
miss returns the nearest candidates, so guess rather than searching for one
first. To learn about the function `NotifyPlayers`, run
`arac read NotifyPlayers`.

A CONTEXT entry's description is usually already the answer; drill in only to
change or deeply understand that neighbour.

Edits re-sync the graph; act on any topology warning that comes back.

Parallelise multiple reads and edits in a single command when possible.

With blocked_tools set, a ## Tool Guard section is appended before that closing line, naming which calls the project denies and that the refusal carries the answer or names the tool that has it.

# Aracne

`.aracne/topology.db` holds a pre-analyzed graph of this Go project: packages,
files, functions, methods, structs, interfaces and package-level variables, with
a one-line description on each and the references between them.

It is the source of truth about this codebase, and it re-syncs after every edit.

## How it reaches you

`arac read <id> <id> ...` returns declarations with their source, the imports
they need, and the context around them. It takes a LIST: pass every ID you
already know you need in ONE call.
[...]

## Resource IDs              — in cli and mcp
## How an ID is spelled      — in intercept_id
## Line ranges              — in intercept_line_ranges
[... per-language ID rules, with examples ...]

## What a read returns
[... the two sections, with a worked output example ...]

## Writing descriptions       — mcp only

## How the graph models this codebase
[... per-language graph semantics ...]

## Guidelines

1. **Reach for a declaration before a file, and a read before a search.** [...]
2. **Ask for everything you need at once.** [...]
3. **Descriptions are usually sufficient.** [...]
4. **Do not re-read.** If it is already in your context, use it.
[... four more ...]

mcp mode's high contract additionally carries a Writing descriptions section: how to work node_list_no_description in batches through the executor sub-agents.

Slash commands

Names are identical in Claude Code and OpenCode; OpenCode variants additionally declare which agent runs them, since a subtask there cannot spawn further subtasks.

Hooks & plugins

The guard and the pre-tool scan are installed unconditionally, independent of the plugins config. The edit-sync hook is installed only when the main agent lists the edit-update-db-plugin plugin.

What the guard hook does

• Pre-call, every mode: runs the scan.pre_tool scan.
• Rewrites a search, every mode. A single, unpiped, unredirected Bash grep that the parser models comes back as arac cmd -- <the original text>, verbatim.
• Rewrites a read in intercept_id and intercept_line_ranges, when the topology knows the target.
• Denies per blocked_tools, in mcp and cli only. A denied read is answered with its content where it can be. Blocking grep also blocks rg / Select-String run via Bash; blocking bash blocks the Bash tool entirely; piped reads (cmd | grep) are exempt unless read.pipe_passthrough: false.
• Post-call nudge on a native Read/Grep/ Edit/Write, which interception never sees. A shell read gets none.

Guard rails on the rewrite: never a second time, never across a pipe, a redirect, a heredoc, an &&, an env prefix or a wrapper; never a mutation; never a file with no topology nodes. See what passes through.

Generated sub-agents

14The Viz menu Full build

arac viz serve                              # → http://127.0.0.1:7331
arac viz serve --addr 0.0.0.0:8080 --db ./other/topology.db

A local HTTP server serving a single-page app embedded in the binary. It makes no network requests, and binds to localhost by default.

The Visualization screen

Visualization mode

Left panel controls

Language

Filter to one language, or All. Useful in a polyglot repo where the merged graph is too dense to read.

Search

Matches function names, paths and descriptions — the same three-way search the CLI grep does. Selecting a hit centres the graph on it.

Neighborhood depth

1–4. With a node selected, renders only what is reachable within that many hops. This is the control that makes a 5,000-node graph legible.

Graph optimization

Opens the optimization-rule editor: add, toggle and favourite rules that collapse or hide noise.

Zoom / Fit

+, − and Fit, above the canvas, alongside a status line with the node and edge counts.

Custom mode filters

Kind

Multi-select over package, file, function, method, struct, named_type, interface, variable, dependency.

Edge kind

Multi-select over the edge types present in this topology.

Strict edges

Keep only edges whose both endpoints survived the node filters, instead of drawing a dangling edge to a filtered-out node.

Path

Restrict to a subtree, e.g. internal/topology.

Limit

Max nodes to render, 1–3000. Default 300.

Inspector & Code tabs

Selecting a node fills the right-hand panel. Inspector shows the ID, kind, language, path and line span, the description, the typed properties, in/out degree and warning count, and — for a collapsed node — what it includes. Code shows the node's source. Graph nodes are keyboard-reachable: tab to them, enter or space to select.

Optimization rules

Rules live in the JSON file named by viz.graph.optimization_rules (default .aracne/optimization_rules.json) and are editable from the UI. A rule is a list of operations ANDed together; a node matching all of them is collapsed out of the rendered graph. Two default rules ship, both aimed at unexported leaf noise.

[
  {
    "id": "default-non-exported-leaf",
    "active": true,
    "favorite": true,
    "operations": [
      { "kind": "non_exported" },
      { "kind": "less_equal_incoming", "value": "1" },
      { "kind": "less_equal_outgoing", "value": "0" }
    ]
  }
]

The Settings page

Reachable from the gear in the top-right. It exposes two things that are genuinely easier in a UI than in JSON:

• Need Description — which resource kinds the no-description tools and description workflows target. Writes descriptions.kinds.
• Provider Settings — add OpenAI, Anthropic, DeepSeek or a Custom provider. A custom provider takes a base URL and a chat contract (which of the three wire formats it speaks) plus a list of possible models, so a gateway, a proxy or a self-hosted model works. Credentials are stored either as a literal key or as the name of an environment variable to read, in .aracne/providers.json.

HTTP API

The SPA is a client of a plain JSON API, which is equally usable from curl or your own tooling.

15Configuration — .aracne/config.json

Written by arac init, rendered into integration files by arac setup, and read by everything. An invalid file is overwritten with defaults. Every tool name in it is validated against the tool catalog at load time, so a typo fails fast instead of silently disabling a tool.

arac setup exits non-zero and names the offending key on an invalid config.

mode

contract_verbosity

preload_mcp_tools

scan & scanner

"ignore": ["dist/", "*.generated.go", "**/fixtures/**"]

read

read.context_filter

grep

terminal

descriptions

Who writes the descriptions

One provider block covers both the sweep and the lazy fill. See Who writes them for the CLI setup.

descriptions.lazy

Accepts both JSON shapes: "lazy": true as a plain switch, or "lazy": {"enabled": true, "max_nodes": 8} with the tuning exposed. It is written back in whichever shape you used.

// the common case
"descriptions": { "lazy": true }

// no API key: both the sweep and the lazy fill go through the CLI
"descriptions": {
  "provider": "cli",
  "cli_provider_command": "claude -p --model haiku --max-turns 1",
  "lazy": {
    "enabled": true,
    "max_nodes": 12,
    "timeout_seconds": 45
  }
}

llm

Per-harness agent configuration. Three blocks: <any>, opencode, claude_code — each with a main_agent and a map of named agents. This is what arac setup and arac serve --tool-profile consult to decide what each agent can do.

Resolution order

1. The per-harness block (claude_code or opencode) wins over <any>.
2. An absent field, or the sentinel "<inherits>" as a model, falls back to the main agent.
3. <any> applies to both harnesses.

Agent fields

"llm": {
  "<any>": {
    "main_agent": {
      "mcp_tools": ["read", "warnings_list"],
      "blocked_tools": [],
      "plugins": ["edit-update-db-plugin"]
    },
    "agents": {
      "descriptions-generation-executor": {
        "model": "<inherits>",
        "mcp_tools": ["read", "update_description"],
        "params": { "max-batch-size": 5 }
      }
    }
  },
  "claude_code": {
    "main_agent": {},
    "agents": {
      "descriptions-generation-executor": { "model": "haiku" }
    }
  },
  "opencode": { "main_agent": {} }
}

viz

paths

"paths": [
  { "path": "my_example",               "hidden": true  },
  { "path": "my_example/another_layer", "hidden": false }
]

Full example

What a project looks like after arac init, annotated. The seven answers are mode, contract_verbosity, the descriptions provider block, the executor's model and preload_mcp_tools; everything else is a default.

{
  "mode": "cli",
  "contract_verbosity": "low",

  "scan": {
    "ignore": [],
    "workers": 0,
    "progress": "auto",
    "pre_tool": "default"
  },
  "scanner": { "update_frequency": 200 },

  "terminal": { "max_overserve": 4 },

  "read": {
    "max_file_size": 524288,
    "kinds": ["file", "function", "struct", "interface"],
    "pipe_passthrough": true,
    "context_filter": "normal"
  },

  "grep": {
    "description_kinds": ["function", "method", "struct", "interface"]
  },

  "descriptions": {
    "kinds": ["function", "method", "struct", "interface"],
    "style_exemplars": 1,
    "lazy": true,
    "provider": "anthropic",
    "api_key_env": "ANTHROPIC_API_KEY"
  },

  "llm": {
    "<any>": {
      "main_agent": {
        "mcp_tools": ["read", "warnings_list"],
        "blocked_tools": []
      },
      "agents": {
        "descriptions-generation-executor": {
          "model": "claude-haiku-4-5",
          "mcp_tools": ["read", "update_description"],
          "blocked_tools": [],
          "params": { "max-batch-size": 5 }
        }
      }
    },
    "opencode": { "main_agent": {}, "agents": {} },
    "claude_code": { "main_agent": {}, "agents": {} }
  },

  "viz": {
    "graph": { "optimization_rules": ".aracne/optimization_rules.json" }
  },

  "paths": []
}

16Environment variables

17Language support

Known quirks worth knowing

• JS and TS are independent topologies. There is no cross-language import resolution between them — a .ts file importing a .js one does not produce an edge.
• Python classes are stored with kind struct, and an ABC subclass yields inherits / inherited_by, not implements.
• Python uses_dependency is signature-scoped. The scanner records the edge only for imports used in a signature, annotation or decorator — never for ones used only in a function body. json.dumps(...) inside a body produces no edge and no import line in a read.
• Go resource IDs are module-path-prefixed. They begin with whatever the module line in go.mod says.
• Interface conflicts are only detected where declaring one is a claim. Go and Python Protocol are structural — a broken type simply has no implements edge.

Files outside the six languages

They are not indexed, so a read or grep on them passes through to the real command unchanged.

18Troubleshooting

The build fails to link the scanners

CGO is off or there is no C compiler. Install gcc and make sure CGO_ENABLED=1. make build sets it for you.

arac viz serve says "this is the Basic build"

You have the Basic binary. Install the Full build: go install github.com/Rhuan-Marques/aracne/cmd/arac@latest, or grab the release asset without the -basic suffix.

Reads and greps are not being answered from the topology

Check, in order:

1. arac check-updates — is the index stale, or was the project never scanned?
2. The mode. Shell reads are only intercepted in intercept_id and intercept_line_ranges. Search is intercepted in every mode.
3. Whether the command has a flag Aracne does not model, or is piped, redirected, or part of a compound command — those pass through by design.
4. Whether the target file has any topology nodes at all. An unindexed language, an ignored path, or a hidden path all mean passthrough.
5. Whether the answer would exceed terminal.max_overserve.
6. That the hook is installed — re-run arac setup and restart the harness. Both harnesses need a restart to pick up new hooks and MCP config.

The agent's reads are missing descriptions

read.context_filter is "normal", so undescribed neighbours are omitted rather than shown blank. Either warm the repo (arac descriptions generate), or let lazy descriptions do it as you work — which needs a provider key in the environment. Check arac node count --no-description to see how much is left.

Descriptions disappeared after a re-scan

--hard clears them. Use --all instead, which preserves them, and keep a sidecar: arac descriptions export before, import after. --min-rate on the import will tell you if the sidecar no longer fits the graph.

A warning will not go away

signature_changed and interface_conflict are derived from current state, so they retire themselves once the code actually fits — but they need a scan to notice. Run arac scan. If it persists, arac warnings list --kind signature_changed names the caller to verify in its TargetID.

The topology has duplicate ../<dir>/… nodes

The database records an absolute root. A copied .aracne/ resolves edited paths against the old directory and silently creates a parallel set of nodes instead of updating the real ones — which produces no warnings at all and looks like a bug. Delete .aracne/ and re-scan after moving or copying a project.

An edit produced no topology update

Native edits are synced by the edit-update-db-plugin hook, which is only installed when the main agent lists that plugin. Either add it to llm.<harness>.main_agent.plugins and re-run arac setup, or rely on the pre-tool-call scan (scan.pre_tool), which catches the drift before the next call reads it.

The scan uses too much memory

Lower scan.workers (or pass --workers 2). A full scan parses files concurrently, one per CPU by default. Adding build output to scan.ignore usually helps more.

arac setup exits with "Invalid .aracne/config.json"

The message names the offending key and, for a tool name, the agent it was found under. Common causes: a tool name that is not in the catalog, an unknown mode, an empty read.kinds, or an unknown descriptions.provider.

Further reading