git that understands your code — for AI agents and the people who review them
Русский · Full guide (RU) · Install guide for agents
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.
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.
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.
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.
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.
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).
| 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 lspasks 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.
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.
- 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.
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 | shcd 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| 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.
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 changesIn 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.
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.
| 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) |
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.
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).
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}
}MIT — see LICENSE.