Skip to content
pnnnxPublic

About

git for AI agents: one call returns a function's code, callers, tests and impact. Edit and rename by symbol, find the culprit of a failing test. Measured on 10 open-source projects.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

gitnext

git that understands your code — for AI agents and the people who review them
Русский · Full guide (RU) · Install guide for agents

CI MIT DOI Preprint Rust

gitnext TUI: files, symbols and a function with its inputs, output, callers and code

gitnext is a drop-in companion to git (gitnext = git + a code index). It parses Rust, Python, C, C++, TypeScript, JavaScript, Go and Java into functions, types and the calls between them, knows which libraries each function calls (with the versions from package.json, go.mod, pom.xml, Cargo.toml, pyproject.toml), and puts that graph to work:

  • agents read one function instead of a whole file, see who calls it and which tests cover it in one call, and rename or edit by symbol;
  • people browse code as a map, see changes as "function X changed" instead of line noise, stage a single function and undo a commit without fear.

The repository stays plain git — GitHub, CI and your other tools keep working.

Results

Everything here is measured on other people's code — ten open-source projects in five languages — and judged by their own compilers and test suites. How each number is obtained and how much of it is noise: eval/results/HISTORY.md. The paper on the model families and the bug-fix hint: preprint, doi:10.5281/zenodo.24406286.

Agents get there in a third of the steps

Tasks solved by three local models: 144 of 216 with plain tools, 163 of 216 with the five gitnext tools

Three local models (Qwen 3.5 4B, 9B and 27B), the same 72 tasks each way — find a function, list its callers, rename it, fix a seeded bug — on six projects in Python, Rust and Go, judged by the projects' own compilers and tests. With the five gitnext tools (gitnext mcp --profile lite) they solve 163 of 216 tasks against 144 with plain read / grep / edit / run (+9 points; the 95% interval is +1 to +17), in a median of 3–4 steps instead of 9–10, and the 27B model sends 2.4 times fewer tokens. The clear gain is a bug fixed by the larger model: 14 of 18 against 7, never the other way round. For one model alone the difference in solved tasks is inside the noise, and an earlier 24-task run that showed 4 against 15 for the 4B model did not repeat: with today's harness the plain model solves 19 of those 24. On a large project (Prometheus, 406 thousand lines of Go; the 4B and 27B models, 36 tasks each way, no bug fixes) the gain is larger: 62 of 72 tasks against 49 (+18 points, the 95% interval is +7 to +31), for a third of the tokens.

Not only Qwen: four other model families

Tasks solved with plain tools and with the five gitnext tools: Gemma 4 12B 55 and 84 of 120, gpt-oss-20b 48 and 77, Ministral 3 14B 51 and 85, Granite 4.1 8B 38 and 85, the four together 192 and 331 of 480, Qwen 3.5 9B 47 and 53 of 72

The same harness, the same gitnext build and the same tasks with models of four other makers — Gemma 4 12B (Google), gpt-oss-20b (OpenAI), Ministral 3 14B (Mistral AI) and Granite 4.1 8B (IBM), 120 tasks each (the 72 above and 48 new ones), 4-bit, on two T4 cards. With the five gitnext tools the four solve 331 of 480 tasks against 192 with plain tools: 69% against 40%, +29 points (the 95% interval is +23 to +35), and each model gains on its own (p < 0.001 for each). Without gitnext the models lie 14 points apart (32–46%), with it 7 points (64–71%). Listing the callers gains most (26 → 99 of 120); fixing a seeded bug stays the weak kind (16 → 40). Qwen 3.5 9B, run again on its 72 tasks as an anchor, solved 47 and 53 (44 and 51 the first time); a single task came out the same in 85% and 92% of cases. Details: eval/results/HISTORY.md (run 10); every run: eval/results/kaggle-families-20261120.

Fixing a bug: prove which change broke the test

Seeded bugs fixed by Gemma 4 12B: 49 of 102 when shown what changed, 91 of 102 when told which change is the cause, 87 of 102 with the proof shortened and two tries

When a test fails, gitnext can do more than show what changed since the tests last passed: it undoes each of those changes on its own and runs the failing test, and the model is told which change makes it pass again. It is not a sixth tool — the agent still has five, and check <test> (or gitnext why <test>) answers with the proof. Gemma 4 12B, the same 102 tasks each way — a seeded bug alone (fix), or the bug committed together with two changes that are meant and must stay (regress), on the six projects:

what the model gets fix regress all
what changed (V1, lite) 28 of 53 21 of 49 49 of 102 (48%)
the change proven to be the cause (V2, prove) 46 of 53 45 of 49 91 of 102 (89%)
the proof, shorter, plus two tries (V4, combo) 49 of 53 38 of 49 87 of 102 (85%)

The proof turns 45 failures into fixes and 3 fixes into failures (+41 points, the 95% interval +30 to +52, p < 0.001), for the same tokens. Combining it with a shorter answer and a try tool that tests two versions of a fix does not help: −4 points against the proof alone (−12 to +4), worse on regress (2 gained, 9 lost), and the model never called try. Gemma 4 31B solves nearly every task either way (116 of 117), so the proof is not needed there and does not get in the way. The runs were made with the proof in the evaluation harness (eval/agent.py --modes prove); since 0.3.2 why and check <test> do it themselves (GITNEXT_PROVE=0 switches it off). Details: eval/results/HISTORY.md (run 11); every run: eval/results/kaggle-fix-variants-20261120.

A failing test leads to the function at fault

Share of seeded bugs where gitnext why names the function at fault first: 18% from the call graph, 86% with the learned coverage map

gitnext why <test> runs the test and answers in a dozen lines: the failure itself, the code the test ran with the most likely culprit first, and the lines that changed since the tests last passed — and which of those changes breaks the test, proven by undoing each one. gitnext learn-tests is one test run with coverage (Python, Go, Rust); a long build or test log goes through gitnext digest (a vitest run with 35 failures: 843 lines → 12).

How accurate the code graph is

Go Python TypeScript Java Rust all
who calls a function — found 100% — 100% 100% 99% 100% ±1
who calls a function — correct 98% — 100% 100% 100% 99% ±1
rename — the project still builds and its tests pass 93% 90% 85% 96% 87% 91% ±3
tests for a function — one of the first 10 named does fail 84% 81% 41% 95% 73% 79% ±6
… with a learned coverage map — failing tests found 100% 100% 100% — 100%

232 functions for callers, 338 renames, 167 functions for tests; ± is the 90% interval, a difference inside it is noise. Python has no compiler to say who calls what, so callers are not scored there. python3 eval/run.py repeats the run; the full table is eval/results/latest.md.

What these numbers are not:

  • The tool was tuned on these ten projects. On fourteen projects it had never seen, measured once (heldout.md): callers found 99%, correct 96%; rename 77%; and where a function is picked whether or not gitnext knows a caller of it, 87% of the callers are found (99% here).
  • A plain search for the name finds every caller too — with one wrong answer in ten instead of one in a hundred. For methods whose name several types share, the search is wrong two times in three, gitnext finds 83% of the callers (73% on the unseen projects), and a language server (gopls, rust-analyzer, tsserver) 97–99% (latest.lsp.md). Where a language server is installed, gitnext lsp asks it once about the ambiguous calls and keeps the answers: on the Go and Rust projects that takes gitnext from 78% to 96%, and from 73% to 93% on the unseen ones (lsp-refined.compare.md).
  • Ten tests picked at random catch a broken function in 61% of cases, so 79% is 18 points above chance; with a learned coverage map the failing tests are named outright.

Fewer steps, less to read

Bytes of code an agent read for six tasks: 49 KB without gitnext, 29 KB recounted, 22 KB with gitnext look

Most of an agent session is the system prompt re-sent on every step, so the win comes from fewer steps, not just shorter output: gitnext look A B C answers what is it · who calls it · what it calls · which tests reach it and how to run them · what a change affects for several targets at once. How to reproduce: integrations/ab.

What is checked, and what is not good yet

  • 153 unit tests; parser output is pinned by fixtures in eight languages; every command and every MCP tool — 86 in all — is run on each of the ten projects (860 calls, none fails). What checks each function: eval/results/COVERAGE.md.
  • The coverage map for Java needs Maven and tests that run on the JUnit Platform (JUnit 5, or JUnit 4 under surefire 3.6 and newer); Gradle is not learned. For JS / TS it needs vitest.
  • A rename breaks the build or the tests in 9% of cases — mostly dynamic access and names shared by unrelated types.
  • Small models rarely fix a seeded bug on their own: 6 of 18 at best for the 4B and the 9B model, and 7–16 of 30 for the four other families with the five tools. Told which change broke the test (above), Gemma 4 12B fixes 46 of 53. With the full tool list they do not start from check <test> (the 9B model never did in 18 tasks) — give them the short list.
  • A rename done with the tool passed the judge no more often than one done by hand (12–13 of 18 against 14): names that are also common words, and mentions in documentation — the latter are renamed now.

Install

cargo install gitnext          # from crates.io (needs Rust: https://rustup.rs)
# or from source:
git clone https://github.com/pnnnx/gitnext && cd gitnext
sh scripts/install.sh          # builds from source (needs Rust: https://rustup.rs)
# or, once a release is published:
curl -fsSL https://raw.githubusercontent.com/pnnnx/gitnext/main/scripts/install.sh | sh

Quick start

cd your-project
gitnext init        # index the code, write the map (.gitnext/map, AGENTS.md)
gitnext setup       # connect Claude Code / Cursor / Codex / loca
gitnext doctor      # check that everything is in place
gitnext             # open the TUI

For agents

Need Command (CLI) / MCP tool
everything about a symbol, several at once gitnext look Agent.execute brief config.py / look
skeleton of a file or folder gitnext outline <path> / outline
edit one function without reading the file gitnext edit replace <Sym> -f new.py / replace_symbol
rename everywhere (imports, tests, __all__, mod.func) gitnext rename <old> <new> / rename_symbol
what breaks, which tests to run gitnext impact <Sym> · gitnext tests-for <Sym> (the 10 most likely to fail + one command for the rest)
which tests really run a function gitnext learn-tests — the tests run once with coverage (Python: pytest-cov; Go; Rust: llvm-tools-preview; JS / TS: vitest with @vitest/coverage-v8; Java: Maven with the JaCoCo agent); tests-for, look, check and why then use the real list
did my change break anything gitnext check — builds and runs the tests of what changed, prints a verdict; a test that fails without the change too is named as not caused by it (gitnext rename A B --check does it right after the rename)
a test fails — why gitnext why <test> / check with test — runs it: the failure in a few lines, the code the test ran with the most likely culprit first, the lines changed since the tests passed, and which change breaks the test (proven by undoing it)
a long build or test log cargo test 2>&1 | gitnext digest — what failed, where, the message (a vitest run with 35 failures: 843 lines → 12)
error or traceback → code gitnext locate (stdin) / locate
where were we gitnext brief · gitnext journal
which libraries the code calls, with versions gitnext libs (and look shows them per function)

gitnext setup writes the MCP config and a short instruction block for each agent; --hooks makes Claude Code see an outline before reading a big file whole.

Small local models. gitnext mcp --profile lite shows five tools instead of 29 — look, replace, add_after, rename, check — with short descriptions and short answers: a 4B model chooses better from a short list. For a model that calls no tools at all, gitnext context "<task>" prints the code the task is about, to put into the prompt.

Git in plain words

Changes screen: one function staged, a commit message suggested

gitnext status            # what changed, by function, with a suggested commit message
gitnext add Task::reopen  # stage just this function
gitnext commit            # offers the message; the symbol list goes into the commit
gitnext undo              # take the last commit back, changes stay staged
gitnext timeline          # every earlier point of the branch; --to N goes back
gitnext branches          # how far ahead/behind each branch is and what it changes

In the TUI: s changes, space stages a file or one function, enter shows before/after side by side, c commit, U undo, H time machine, B branches, ctrl-p every action.

Project overview: languages, areas, entry points, dependency layers

Overview (o): languages and size, areas and their purpose, entry points (main, HTTP routes, CLI), dependency layers — foundation at the bottom, its users on top.

How it works

Repository → parsers → index → code graph → map, CLI, TUI, MCP

Folder What it does
crates/gitnext-parse tree-sitter parsers → symbols (kind, signature, inputs, output, docs) and references. Rust, Python, C, C++ have their own extractors; TypeScript, JavaScript, Go and Java go through one table-driven engine (generic.rs + a table per language in specs.rs)
crates/gitnext-index incremental SQLite index, code graph (callers, impact, inheritance, layers), semantic diff
crates/gitnext-core git plumbing on libgit2: status, commit, stage by line range, undo, branches, reflog
crates/gitnext-docs the map: .gitnext/map/**/DIR.md and the block in AGENTS.md
crates/gitnext-ops features: look, edits and rename, changes in words, history, insight, agent setup, explain, LSP
crates/gitnext-cli the gitnext command and the MCP server
crates/gitnext-tui the terminal UI
integrations/ A/B test kit for real agents, loca (llama.cpp) benchmark
eval/ the measurements: run.py (accuracy on ten projects), agent.py (a local model on real tasks), why_rank.py (seeded bugs), smoke.py (every command on every project)

Status

Early, and used daily on its own code (this repository is indexed by gitnext — see AGENTS.md). Languages: Rust, Python, Go, Java, TypeScript, JavaScript, C, C++. Name-based resolution is approximate for dynamic code; gitnext lsp refines it with rust-analyzer / pyright / clangd. Every change to what the tools answer is measured before it is merged: eval/results/HISTORY.md.

Similar projects

Each piece exists elsewhere; gitnext puts them in one tool and measures the effect.

Project What it does How gitnext differs
Aider repo map tree-sitter map of the repo in the prompt the map is committed to the repo (AGENTS.md, .gitnext/map), so any agent — even a small local model without tools — gets it
Serena MCP tools to find, edit and rename by symbol, via language servers one call look returns code + callers + callees + tests + impact; works without a language server (LSP is optional refinement)
CodeGraph, CodeGraphContext code graph over MCP: callers, callees, impact also injects the code a task needs before the request (gitnext context) for agents that do not call tools
sem entity-level diff, blame and impact on top of git adds plain-language git: stage or commit one function, undo, timeline, commit message from changed functions
lazygit, GitButler friendly git UIs the TUI shows code by function and relation, not only files and hunks

What we can show that others do not: accuracy against compilers and tests on ten projects, and the effect on a real agent — including a 4B local model (eval, integrations/ab, integrations/loca).

Citing

The software: every release is archived on Zenodo — the DOI badge above points to the latest (0.3.2: doi:10.5281/zenodo.24406143); CITATION.cff gives the details, and GitHub's "Cite this repository" uses it. The evaluation of the five tools across model families and of the bug-fix hint:

@misc{kononenko2026gitnext,
  author    = {Kononenko, Leonid A.},
  title     = {Code Navigation Tools for Local {LLM} Agents: Five Model Families, and a Proven Cause That Doubles Bug Fixes},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.24406286},
  note      = {Preprint}
}

License

MIT — see LICENSE.

About

git for AI agents: one call returns a function's code, callers, tests and impact. Edit and rename by symbol, find the culprit of a failing test. Measured on 10 open-source projects.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages