codeterrain

terrain: exact answers about your code, in under a second.
For coding agents, and the people working beside them.

Local only  ·  no LLM  ·  no network calls of its own  ·  Python, pytest, FastAPI  ·  JavaScript and TypeScript front ends  ·  Terraform

Quick start  ·  What it answers  ·  Results  ·  Token savings  ·  How it works  ·  Docs

A coding agent spends most of its reading on structure it has to rediscover every session: which fixtures a test really gets, where a route is handled, who calls a function, which tests would catch a change to it. The answers are in the code, but finding them takes rounds of grep and file reads, and a wrong guess costs a review round.

terrain answers those questions from a cache, the way the framework itself would answer them.

Quick start

uv tool install <path-to-this-checkout>     # Python 3.12+; the only dependency is pluggy
# or "<path-to-this-checkout>[terraform]" to add the Terraform language pack, "[typescript]"
# to read front-end calls with tree-sitter, "[terraform,typescript]" for both
cd your-repo
terrain doctor                              # what it found, and which config it used

Ask about a function: where it is called, how each call passes its arguments, and which tests patch it. This is terrain run on its own source:

$ terrain refs is_test_module
function codeterrain.fixtures_static.is_test_module(rel)  src/codeterrain/fixtures_static.py:327
6 calls (6 in code, 0 in tests), 0 with a shape problem, 0 used as a value, 0 patched
file:line                                 in                             shape         note
src/codeterrain/code_static.py:1349       update                         1 positional
src/codeterrain/code_static.py:1357       update.<listcomp>              1 positional
src/codeterrain/fixtures_static.py:322    unlisted_test_trees.<genexpr>  1 positional
src/codeterrain/fixtures_static.py:435    build                          1 positional
src/codeterrain/impact.py:272             _Fixtures.__init__             1 positional
src/codeterrain/impact.py:424             _inherited_tests               1 positional

Ask which tests would catch a change to it, through its callers and the fixtures that call them (abridged):

$ terrain impact is_test_module --depth 2
17 tests reach codeterrain.fixtures_static.is_test_module (0 directly), through 15 callers within 2 levels; 2 tests patch it …
test                                                 depth  how                               via
tests/test_cli.py::test_a_handler_is_matched_by_…    2      call at tests/test_cli.py:1186    …update <- …is_test_module
tests/test_cli.py::test_a_route_text_that_matches_…  2      call at tests/test_cli.py:1142    …update <- …is_test_module
…

Ask what a fixture is and what depends on it (from the sample repository in tests/sample_repo):

$ terrain fixture db
name: db
scope: session
autouse: no
params: none
deps: _env_session
defined: tests/conftest.py:9
overrides: -

dependents (4):
fixture  _reset_state  tests/conftest.py:19  arg
fixture  client  tests/conftest.py:34  arg
fixture  mod_cache  tests/conftest.py:14  arg
…

The commands that import your application (setup-order, routes) run in the target's interpreter: pass --python .venv/bin/python or set CODETERRAIN_PYTHON. Add --json to any command for the full data.

What it answers

Every option is in docs/commands.md.

Results

Measured read-only on real code bases: a large FastAPI backend with a very large test suite, three smaller Python code bases, an analytics project with a large fixture graph, and five front ends.

impact is the one answer over a second: it walks callers and fixtures, and on the backend a heavily tested function is reached by about a thousand tests. A cold build costs seconds for the static index and about a minute and a half for the routes. After that, answers come from the cache, and a view is stamped stale when files change.

The saving scales with the code. Where the fixture graph is large, an answer is a small fraction of the grep-and-read it replaces. In a small suite with a couple of fixtures the answer can be longer than the grep; there the gain is the exact order, which grep can't show.

In the field

Coding agents working on real tasks logged each terrain lookup: what they asked, whether the answer was right, and what they would have done instead.

• Each fully answered lookup saved the agent about 1.3 tool calls, by its own count.
• No answer was marked wrong. The partial answers came from output cut by the token budget, a cache built from a different checkout than the one being edited, and a value read through a module alias.
• Most errors were the wrong command: callers, which is for routes, where refs was meant.

Inferred token savings

An estimate from the two measurements above, not an A/B experiment:

Lookups are only part of a session: reasoning, editing and test runs are untouched, and small code bases save little. Tokens here are characters divided by four. A session-level A/B, the same lane run with and without terrain, is the next measurement. The method and the per-repository results are in docs/why-codeterrain.md.

How it works

flowchart LR
    ask(["agent or you: terrain refs NAME"]) --> cache[("cache per repository,<br/>keyed on content")]
    cache -->|warm| answer(["answer in under a second"])
    subgraph static ["Static tier: reads files, never runs them"]
        fixtures["fixtures and tests<br/>(ast)"]
        code["code index<br/>(ast, SQLite)"]
        calls["front-end HTTP calls<br/>(tree-sitter, or the JS/TS tokenizer)"]
    end
    subgraph sandbox ["Import tier: sandboxed subprocess"]
        order["setup order<br/>(pytest --collect-only)"]
        routes["routes<br/>(imports the apps)"]
    end
    static -->|incremental, changed files only| cache
    sandbox -->|on refresh; served stamped stale| cache

• The static tier reads source with Python's ast, and front-end files with tree-sitter when the TypeScript pack is installed (chosen for speed and accuracy) or a tokenizer written in Python when it is not. It never imports or runs the target, and re-reads only the files that changed.
• The import tier needs the real framework: pytest's fixture resolution, FastAPI's route table. It runs in a subprocess using the target's own interpreter, with an allowlisted environment, dummy cloud credentials, no proxy and a best-effort network guard.
• The cache lives outside the checkout, in the git common directory or your user cache, and is keyed on content hashes.

More in docs/how-it-works.md, docs/sandbox.md and SECURITY.md.

Why this exists

codeterrain started inside benchli, the team sports platform built by Mitbolas GmbH. Its Python backend is a large FastAPI service with a very large test suite, developed with coding agents. Most of the agents' tokens went on re-mapping the same structure every session, and a hand-kept map went stale within weeks. The goal became exact answers, straight from the code, locally and in under a second, in every repository benchli and Mitbolas develop with agents. The full story, and why we did not adopt a knowledge-graph tool, are in docs/why-codeterrain.md.

Documentation

Development

uv run --extra dev ruff check .
uv run --extra dev pytest

Run pytest as a single process (no -n). The suite spawns real pytest and interpreter subprocesses, and a few tests skip on Windows (no sendmsg, no unix-domain sockets). CI also runs it against FastAPI below and above 0.137 and pytest 8 and 9. Contributor and review rules are in AGENTS.md.

Copyright Mitbolas GmbH. Licensed under Apache-2.0 (see LICENSE and NOTICE).