Core concepts

Archis's index is a graph, not a text search index. That distinction is the reason it can answer a question with three lines instead of three files: a text index can tell you where the word retry appears, but only a graph can tell you that a function called retry is called from four places, two of them in the payment path.

It lives in a .chi directory beside your .git, and every command finds it the way git finds its own — by walking up from where you are. --db points at a different one when you need to.

chi index both builds it and keeps it current, and works out which it needs to do: an empty graph is indexed whole, an existing one has only its changed files recompiled and its deleted ones forgotten. Name a file — chi index src/router.ts — to refresh just that file, and --full to rebuild from scratch. In normal use you run none of it: the index refreshes itself when a model asks it something.

A symbol is a declaration your code makes: a function, a method, a class, a struct, an interface, an enum, a constant, a field. Each one has a stable id, a kind, a file, a line span, and a signature.

Ids are the currency of the CLI. chi search gives you ids; chi symbol takes them. Two symbols with the same name in different files are different symbols, which is why chi search --file exists — it disambiguates by path substring rather than making you guess which of the four parse functions was meant.

A relation is an edge between symbols — most usefully, one symbol calling another. Relations are what turn a list of declarations into something you can reason about, and they are the part a text search cannot reconstruct.

Relations are a question about a symbol, so they are asked of chi symbol. --refs gives both directions at once, which is the question people actually have. Narrow it with --called-by or --calls. Add --impact for the transitive callers — the blast radius of a change — and --depth to say how far to follow. Impact is the expensive direction, which is why it is asked for rather than included.

This is the idea behind Archis. Any question about code can be answered at several depths, and most questions do not need the deepest one. Archis serves the shallowest depth that answers, and escalates only when the job genuinely needs more.

On the CLI the choice is explicit: chi symbol <id> --detail takes signature, behavior (the default) or source. Over MCP the agent picks, and the whole reduction comes from the fact that a well-briefed agent picks the shallow one far more often than it reads a file.

chi compile <file> prints the compact projection of a single file, which is the fastest way to see what the level actually looks like on code you know.

A budget is a token ceiling on an answer. Ask for more than fits and the response is cut by rank rather than by accident, and it says so — you get the count of what was left out instead of a silently truncated list.

Budgets are what make the trade-off yours rather than ours. Turn one down and you get fewer symbols in more compact form; turn it up and you get more. The interactive example lets you move one and watch the answer change.

Two related knobs appear on chi run: --budget caps the whole context, and --source-budget caps exact source specifically — once spent, further source reads are refused in favour of compact ones. --plan is the extreme case: compact only, never exact source.

Every count is a real tokenizer count, not an estimate. --tokenizer selects which one — o200k by default, cl100k for older models — and it matters for comparisons, so keep it fixed across a set of measurements.

By default: your repository, and not its dependencies, build output or hidden directories. That default is what makes the first index finish in a reasonable time — indexing node_modules or target is an order of magnitude more work for context nobody asks about.

• .chignore in the repository root excludes paths, in the same spirit as .gitignore.
• chi index --no-prune overrides all of it, including .chignore. It is asked for rather than assumed because of what it costs.
• chi index --detect reports the languages found and how well each is supported, and writes no graph.
• chi index --detect --opaque also records the files no adapter understands, so they are at least findable even though nothing can parse them.

A session is working memory for one piece of work, stored beside the graph. It remembers what has already been served, so a long task does not pay twice for the same symbol, and it survives the agent process — which is what makes rehydration possible after a restart or a context reset.

chi session report is the honest one. If a session spent more than you expected, it says which level it went to and why, rather than reporting a total and leaving you to trust it.

Support is not binary. A language can be understood at the level of declarations, or of calls, or of types, and Archis is honest per language about which layers it reaches — with the consequence that results are better in some parts of a polyglot repository than others.

The matrix is the capability view; --coverage is the per-layer semantic score, which is the number to watch if you are evaluating Archis on a language you care about. Files no adapter understands are not silently dropped — see --opaque above.

Before you install, here is the published picture, from our benchmark as of 2026-10-05. Capability is a score on small fixtures, a ceiling; the two recall columns are measured on real repositories against independent parsers, and a dash means that language was not re-measured in the latest run.