codeterrain

codeterrain: 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 reach 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.

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

Quick start

uv tool install codeterrain     # Python 3.12+; the only dependency is pluggy
# or "codeterrain[terraform]" to add the Terraform language pack, "codeterrain[typescript]"
# to read front-end calls with tree-sitter, "codeterrain[terraform,typescript]" for both
cd your-repo
codeterrain doctor              # what it found, and which config it used
codeterrain fixtures            # every pytest fixture, and which definition wins where

The same command is also installed as terrain, a shorter name. Another tool on PyPI installs a terrain command too; with both installed, the last one wins, while codeterrain is always this one. To work on codeterrain itself, install from a checkout instead: uv tool install --editable <path-to-checkout>.

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

$ codeterrain 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 statically reach it, through its callers and the fixtures that call them (abridged). A test that reaches a function does not necessarily check what you change, and an empty list does not prove the change is untested:

$ codeterrain 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):

$ codeterrain 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.

Telling your agent

An agent uses codeterrain when its instructions say when to. A starting point for AGENTS.md or CLAUDE.md:

## Code structure: ask codeterrain first

Before grepping or reading files for one of these, run `codeterrain` in the repository root
(local, under a second when warm; add `--json` for the full data):

- where a name is defined: `codeterrain def NAME`
- who calls, passes or patches it: `codeterrain refs NAME`
- which tests statically reach it: `codeterrain impact NAME` (a starting point, not proof of coverage)
- which fixtures a test gets, in order: `codeterrain setup-order NODEID`
- a fixture and what depends on it: `codeterrain fixture NAME`
- where a route is handled: `codeterrain route METHOD PATH`
- a front end's HTTP calls, and the backend routes they hit: `codeterrain calls`, `codeterrain callers`

When codeterrain says it cannot resolve something, fall back to grep. `setup-order` and the route
commands import the code: use them only on code you trust.

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 codeterrain lookup: what they asked, whether the answer was right, and what they would have done instead. 160 lookups, 26 October to 2 November 2026, across the code bases above. Each agent judged its own answer against what it then read or ran; nobody checked the judgements independently. Every lookup has one outcome; the shares are rounded, so they can add up to 101%.

• Each fully answered lookup saved the agent about 1.8 tool calls, by its own count.
• Two answers were marked wrong. In one, fixture answered a fixture of a live-test folder it did not read with a unit-test fixture of the same name; fixtures, fixture and doctor now name such a folder. The other, routes missing an app's support routes, was misjudged: a later lookup found them in the view, below the token budget's cut, whose "more" notice a grep had removed.
• The partial answers came mostly from output cut by the token budget; the rest from a cache built from a different checkout than the one being edited, reads refs does not see (through a module alias, as a dict key), duck-typed calls, and route filters that matched less than expected.
• Most errors were the wrong command or arguments: 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 codeterrain, is the next measurement. The method and the per-repository results are in docs/why-codeterrain.md.

How it works

• 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. Those stop accidents, not hostile code: it imports and runs the target, so use it on code you trust.
• 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).