Open source Works with Codex, Claude Code, and Antigravity

Visit GitHub

A calmer way to explore a codebase

Less context.
More coding.

TokGuard helps your coding agent find the right files, read only what matters, and keep command output under control.

TokGuard in a repository

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

Your agent doesn’t need
the whole repo.

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.

Strong benchmarkMeasured tokens
Without TokGuard47,383
With TokGuard17,295

Token count calculated from the reported 63.5% reduction.

A task, followed through

See a task find its path.

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.
Follow the context
Maptg map
tg/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.

Findtg find generate_repo_map
tg/map.py → generate_repo_map()

The symbol is defined in TokGuard’s map module.

Readtg read tg/map.py 1-25
Selected 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

Just enough to keep moving.

Map

Get a compact outline of files and symbols before opening code.

tg map

Find

Locate a symbol or pattern and see a small amount of nearby context.

tg find calculate_total

Read

Open a relevant line range or symbol body instead of a whole file.

tg read src/app.py 42-58

Run

Filter progress noise and keep useful summaries and errors visible.

tg run -- pytest -q

A new chapter · TokGuard 2.0

Keep the agent
with the task.

TokGuard 2.0 brings planning, drift checks, verification, and automatic updates into the same focused workflow.

2.0THE TASK, START TO FINISH
01 / PLAN

A task manager for the original request

TokGuard locks the request, then helps the agent make a clear work order with scope, ordered steps, and checkable acceptance criteria.

Prompt→Work order→Steps
02 / DRIFT

Notice scope drift as it happens

Baseline-aware checks compare changes with the approved scope and steps. When work drifts, TokGuard explains why and points the agent back.

Scope check ON TRACK
03 / FINISH

Verify, hand off, keep going

Run the declared verification and acceptance checks. When a session budget fills, TokGuard saves context and rolls into a fresh session.

✓ Acceptance✓ Verification↻ Handoff
04 / STAY CURRENT

Automatic updates at launch

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.

Older global installs need one update to 2.0.1 to receive the updater.

Strong benchmark

−63.5%

fewer input tokens used with TokGuard

More room
for the work.

Without TokGuard47,383 tokens
With TokGuard17,295 tokens

8–10 repositories · 10 tasks per repository · 5 runs per task · 800–1,000 total runs across two modes

Explore the benchmark

One setup, familiar tools

One setup. Your usual tools.

Connect TokGuard to the coding agent you already use.

Other MCP clients

Connect from another client that supports the Model Context Protocol.

See setup steps

A useful distinction

Why not just grep?

Each tool has a place. TokGuard helps shape what an agent receives across a few common repository tasks.

What each approach typically returns to a coding conversation
ApproachWhat it returnsContext size
grep / ripgrepMatching lines from a search patternDepends on the match and command options
Agent built-in searchSearch results chosen by the clientVaries by agent and configuration
TokGuardRepo maps, focused matches and reads, filtered command outputDesigned to keep results targeted

Start in a minute

Put TokGuard to work.

Run setup in PowerShell, restart your coding agent, then start with a map of the repository.

  1. 1
    Run the command

    Setup adds TokGuard’s MCP connection and guidance.

  2. 2
    Restart your agent

    Let it load the updated configuration.

  3. 3
    Start with a map

    Ask your agent to run tg map.

PowerShellRecommended
npx -y tokguard@latest setup

Prefer a global install?

npm install -g tokguard@latest
tokguard setup

Setup 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

Smaller context.
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