Git MCP token benchmark: repo.brief vs CLI.
On a deterministic 44-commit, 40-file test repository, a broad 10-command Git orientation sweep produced 1,790 output tokens. One repo.brief call returned its bounded repository overview in 561 tokens.
What did the Git MCP token benchmark find?
repo.brief used 561 output tokens and 1,918 bytes in one call. The broad CLI orientation sweep used 1,790 output tokens and 6,861 bytes across ten calls. That is 3.2x fewer output tokens, 3.6x fewer bytes and one round trip instead of ten for this test. The comparison measures tool output only.
The CLI side deliberately represents a broad orientation pass: repository status, 30 recent commits, branches, unstaged and staged diffs, remotes, stashes, tags, tracked files and submodule status. The MCP side is one typed overview containing HEAD and branch, upstream and ahead/behind state, an in-progress operation, working-tree counts, stash count, recursive submodule drift, ten recent commits and detected commit conventions.
The information sets overlap but are not identical. The wide CLI sweep includes raw diffs, remotes, tags and the full file list; repo.brief returns a bounded situational overview. This benchmark answers how much output each orientation strategy produced on the same repository. It does not claim field-for-field equivalence.
The ten CLI calls.
Each count is normalized stdout, measured with gpt-tokenizer 3.4.0 using o200k_base.
| Command | Bytes | Tokens |
|---|---|---|
git status | 608 | 163 |
git log --oneline -30 | 1,721 | 433 |
git branch -a -v | 678 | 169 |
git diff | 1,478 | 390 |
git diff --cached | 1,314 | 341 |
git remote -v | 75 | 24 |
git stash list | 45 | 14 |
git tag -n | 70 | 21 |
git ls-files | 872 | 235 |
git submodule status | 0 | 0 |
| Total | 6,861 | 1,790 |
The counterexample matters.
A hand-tuned minimal CLI subset was smaller.
When the CLI side was reduced to only status, a ten-commit log, branches, stashes and submodule status, it produced 492 tokens and 1,892 bytes across five calls. repo.brief produced 561 tokens and 1,918 bytes in one call. On output tokens alone, repo.brief cost 14% more than that minimum. The reliable advantage in this sub-check is one call instead of five, not fewer output tokens.
| Orientation strategy | Calls | Bytes | Tokens |
|---|---|---|---|
| Broad CLI sweep | 10 | 6,861 | 1,790 |
repo.brief | 1 | 1,918 | 561 |
| Hand-tuned minimal CLI subset | 5 | 1,892 | 492 |
Methodology.
Deterministic repository
The harness creates a synthetic repository with 44 commits on main, 48 branch-reachable commits, 40 tracked files in 11 directories, four local branches, two annotated tags, one stash, two staged files, two unstaged files, one untracked file, a local bare origin and one deliberate branch conflict. The builder fixes locale, time zone, Git configuration, commit dates and author identity.
MCP implementation
The benchmark built fluxgit-mcp-sidecar 0.1.0 from source and drove it over stdio JSON-RPC in standalone free-shell mode. The source repository commit was 25e45ea8af86cedc325be0e68c7321d2bb10eab7; the sidecar source tree was 89cb8910019ac893198b36a4c8f1dd41091a18b2. The session used the MCP protocol 2024-11-05 specification and returned 34 tool schemas.
Counting boundary
CLI counts use stdout after every absolute benchmark path is replaced with the literal $BENCH_ROOT. MCP counts use the normalized content[0].text payload. The JSON-RPC envelope is excluded from both headline counts; raw MCP wire bytes remain recorded in results.json. Normalization happens before byte and token counting.
Tokenizer and environment
The run used Git 2.50.1 (Apple Git-155) and gpt-tokenizer 3.4.0 with the o200k_base encoding. The dependency is pinned in the published lockfile. Repository and conflict invariants are checked before the run completes, then SHA-256 checksums are verified.
Two results that prevent overclaiming.
Structured conflict data cost more output.
git merge-base plus git merge-tree --write-tree used 179 tokens in two calls. repo.conflictPreflight used 245 tokens in one call. Both found the conflict. The MCP value was a typed status, path list and workingTreeMutated: false, not token savings.
Semantic precision did not make the full payload smaller.
In a separate connected-path synthetic refactor test, raw git diff used 3,650 tokens and diff.semantic used 8,275. FluxGit makes no token-saving claim for semantic diff; its measured benefit was isolating real token changes inside formatting churn.
The complete tool schema has a cost.
tools/list for 34 tools was 41,758 bytes and 9,342 tokens once per session. At the measured 1,229-token wide-sweep difference, that cost is recovered after about eight orientation sweeps. MCP hosts may cache or summarize schemas; this run did not measure host behavior.
Limitations.
- The repository is synthetic. It has 40 files, 44 commits on
mainand small diffs. Larger repositories may produce more CLI output, but this benchmark did not test that and makes no extrapolated claim. - The tokenizer is a proxy. Counts use
o200k_base. Other model tokenizers can change absolute counts. Raw bytes are published beside tokens so the comparison can be inspected independently. - Only output is counted. Requests, latency, model reasoning and the cost of re-reading context after each call are excluded. Those costs may favor fewer calls, but they were not measured.
- Conflict preflight did not save tokens. On this repository the raw Git route used 179 tokens and the MCP route used 245. Its measured differences were structure, one call and non-mutation metadata.
- The execution paths differ by scenario. The orientation and conflict tests used standalone sidecar free-shell mode. The semantic-diff test used the connected sidecar-to-gateway-to-diff-engine path with a hand-registered repository and headless gateway.
- Semantic diff was one synthetic run. Its 2.3x larger payload may change with a different mix of formatting, moves and new code. No broader ratio is claimed.
- Schema overhead is workload dependent. The full 34-tool list cost 9,342 tokens in this legacy-protocol capture. Hosts may cache, filter or summarize it. The protocol response also omitted tool annotations, so no read-only annotation count is inferred.
Reproduce the benchmark.
From a FluxGit source checkout, run the published harness. It builds the sidecar, creates the synthetic repository, captures and normalizes output, counts tokens, checks invariants and verifies checksums.
cd product/web/research/git-context-token-benchmark/benchmark
./run-benchmark.sh
shasum -a 256 -c SHA256SUMSUse SKIP_SIDECAR_BUILD=1 only when intentionally reusing the release binary. The public artifact README documents each file and the exact measurement boundary.
Primary references: the official Git manuals for status, log, diff and ls-files; the captured MCP specification version; and the tokenizer implementation linked above. Benchmark claims remain limited to the downloadable fixture and outputs.
Data and source downloads.
These are the normalized artifacts behind the numbers on this page. The checked-in checksum file covers every captured CLI and MCP response plus the results and manifest.
Browse every captured CLI and MCP output
- CLI: status, 30-commit log, branches, unstaged diff, staged diff, remotes, stashes, tags, tracked files, submodules and 10-commit log.
- Conflict CLI: merge base and merge tree.
- MCP: repo.scope, repo.brief, repo.conflictPreflight and tools/list.
Use the MCP tools.
Explore the Git MCP hub, inspect the complete FluxGit MCP feature and trust boundary, or follow the setup guide for any MCP-compatible coding agent.
Context first. Human approval before writes.
The read-only MCP shell can inspect plain local Git. The FluxGit desktop app adds proposal review, approval, recovery context and an operation audit trail.