tg maptg/map.py → generate_repo_map(), find_symbol() tg/cli.py → cmd_map(), cmd_find(), cmd_read()
TokGuard’s repository map lists real project files and symbols.
Open source Works with Codex, Claude Code, and Antigravity
Visit GitHubA calmer way to explore a codebase
TokGuard helps your coding agent find the right files, read only what matters, and keep command output under control.
tg map
tg/map.py generate_repo_map(), find_symbol()
tg/cli.py cmd_map(), cmd_find(), cmd_read()
tg find generate_repo_map
tg/map.py generate_repo_map()A more focused starting point
Large file dumps and noisy command output can fill a conversation with details the agent may not need. Repeated reads add more of the same.
TokGuard offers a compact map, targeted search, careful reads, and cleaner command results, so the conversation can stay focused on the task.
Token count calculated from the reported 63.5% reduction.
A task, followed through
Start with the request. Follow the useful context from a repository map to the implementation.
The task
“Find where the total is calculated and inspect the implementation.”
One request. A few focused steps.tg maptg/map.py → generate_repo_map(), find_symbol() tg/cli.py → cmd_map(), cmd_find(), cmd_read()
TokGuard’s repository map lists real project files and symbols.
tg find generate_repo_maptg/map.py → generate_repo_map()
The symbol is defined in TokGuard’s map module.
tg read tg/map.py 1-25Selected source range from tg/map.py
Read only the range needed to inspect the implementation.
Illustrative tool flow, not a benchmark task.
Four tools, one workflow
Get a compact outline of files and symbols before opening code.
tg mapLocate a symbol or pattern and see a small amount of nearby context.
tg find calculate_totalOpen a relevant line range or symbol body instead of a whole file.
tg read src/app.py 42-58Filter progress noise and keep useful summaries and errors visible.
tg run -- pytest -qA new chapter · TokGuard 2.0
TokGuard 2.0 brings planning, drift checks, verification, and automatic updates into the same focused workflow.
TokGuard locks the request, then helps the agent make a clear work order with scope, ordered steps, and checkable acceptance criteria.
Baseline-aware checks compare changes with the approved scope and steps. When work drifts, TokGuard explains why and points the agent back.
Run the declared verification and acceptance checks. When a session budget fills, TokGuard saves context and rolls into a fresh session.
With TokGuard 2.0.1, a global install checks npm when it starts. If a newer release is available, it updates and resumes your command. npx tokguard@latest already requests the latest release.
Strong benchmark
−63.5%
fewer input tokens used with TokGuard
8–10 repositories · 10 tasks per repository · 5 runs per task · 800–1,000 total runs across two modes
Explore the benchmarkOne setup, familiar tools
Connect TokGuard to the coding agent you already use.
Add TokGuard tools and repository guidance to your Codex workflow.
See setup stepsUse compact maps, targeted reads, and quieter command output.
See setup stepsRegister TokGuard as an MCP server for your projects.
See setup stepsConnect from another client that supports the Model Context Protocol.
See setup stepsA useful distinction
Each tool has a place. TokGuard helps shape what an agent receives across a few common repository tasks.
| Approach | What it returns | Context size |
|---|---|---|
| grep / ripgrep | Matching lines from a search pattern | Depends on the match and command options |
| Agent built-in search | Search results chosen by the client | Varies by agent and configuration |
| TokGuard | Repo maps, focused matches and reads, filtered command output | Designed to keep results targeted |
Start in a minute
Run setup in PowerShell, restart your coding agent, then start with a map of the repository.
Setup adds TokGuard’s MCP connection and guidance.
Let it load the updated configuration.
Ask your agent to run tg map.
npx -y tokguard@latest setupPrefer a global install?
npm install -g tokguard@latesttokguard setupSetup updates agent MCP configuration and guidance files on your machine. Your repository stays on your machine. Setup is documented for PowerShell. For other shells, see the README.
Clear expectations
TokGuard reduces unnecessary repository and command output. It can’t control hidden model reasoning, and savings depend on the agent following its instructions.
Read the known limits