title: "AI Token Optimizer — Cuts Costs, Sharpens Focus, Blocks Prompt Injection" description: "Cuts AI tool costs 40–80% and guards against prompt injection. Stops re-reads, extracts one function vs. whole file, shrinks screenshots 97%." image: /token-goat/assets/goat-social.png permalink: /

Token-Goat

Give the model what it needs, not everything you have.

85% smaller reads · 97.4% image compression · 180+ filter & interception rules · 94–99% skill overhead cut · compaction memory · prompt injection guard · 3.7 GB never reached the model · 1.1 Gt tokens saved

Reduces AI token use/costs by 40–90%, and improves its focus. Fully automated, always online.

Also defends against prompt injection. Every fetched page is scanned for attack patterns and wrapped in an untrusted-content fence before hitting the model. One config line to disable.

Your AI re-reads the same file three times. Every compaction causes amnesia. Every build log buries the one line that matters. You pay for all of it. Token-Goat fixes all of it — automatically.

Token-Goat sits silently between your AI and your tools. Re-read a file? It gets a one-line hint and a narrow-slice suggestion instead of the full file again. Grab a screenshot? A 100 KB copy reaches the model instead of 10 MB. Run pytest, npm install, docker build, or cargo? The thousands of progress bars and passing-test names are stripped to the failures before the output even reaches the context window. Open a PDF, a large Markdown doc, or a CSV? The hook intercepts it — heading tree, page count, or column preview — so the model never pays for the full file. Run gh run watch or next dev a second time? Prior output is recalled rather than re-run. Compact a long session? It gets a clean structured manifest of edited files and key symbols so nothing important is forgotten. Sessions drop 40–90%+ in cost. You change nothing about how you work.

Works with Claude Code, Gemini CLI, Qwen Code, Codex CLI, Aider, Cursor, Cline, Windsurf, Copilot CLI, Kimi Code, Grok CLI (xAI Grok Build), and OpenCode, plus pi (pi-coding-agent).

Ask your AI to install it fully (give it this GitHub link), or install in one command:

npm install -g token-goat && token-goat install

Restart your AI sessions. Run token-goat stats a couple of minutes after your next session to see the massive savings. It also doubles as a great tracker of your work. Welcome to token efficiency.

Built and continually improved, free, by one person. If it saves you tokens, drop a ⭐️ at the top of this page. One click. Makes my day. Also, if you'd like anything added, drop me a line.

Install · CLI · What gets installed? · Stats · Security & uninstall

_{Same requirements, smarter input: fewer input tokens, shorter answers, and context that stops compounding across rounds}

_{Stats display — gradient bars, sparklines, and a calendar heatmap in 24-bit color}

The problem

AIs read auth.py. Then reads it again. And again. Then a third time after compaction wipes the session. Then it can't find what it wanted and searches other lines and files. You pay for every token and most of it is waste.

Long sessions accumulate waste five ways. Screenshots cross the model at full resolution. A single PNG can land at 10+ MB. The agent re-reads files it already parsed earlier in the same conversation. When a session compacts, the summary LLM doesn't know which files were edited or which symbols mattered, so it preserves the wrong things. And every pytest, npm install, docker build, or git log dumps thousands of lines of progress bars, deprecation warnings, and passing-test names that bury the one line that actually matters.

The fifth waste is skills. A single large skill injects 10k–65k tokens every time. Run a five-iteration /improve loop and you've paid for five full copies of the same rules. Token-Goat now blocks repeat skill loads before they happen: a PreToolUse hook intercepts the second invocation, serves the cached compact (~400 tokens) instead, and only allows a reload when compaction may have evicted the skill from context. It also intercepts direct reads of skill files and ensures the compaction manifest carries the full skill index — so nothing is forgotten and the full body never re-enters context unnecessarily.

The fastest way to reduce AI token costs is fixing these five, not writing shorter prompts. Each one is preventable. Token-Goat intercepts all five, automatically.

What changes

On a per-token API plan, 100K wasted tokens per session runs about $0.30. Five sessions a week is ~$450/year. AI coding cost reduction at that scale comes from fixing the waste, not from using the product less. Token-goat is free. And on subscription plans, it can result in limits feeling 10x higher.

Not just source repos

token-goat semantic works on any folder of markdown, not only source code — a notes vault, an agent-memory directory, a docs folder. Project-root resolution falls back to treating any directory as an ad-hoc project when no .git/package.json/other marker is present, so there's no setup beyond indexing the folder.

cd ~/notes                  # or any plain folder of .md files, no .git required
token-goat index . --walk   # non-git folders need --walk (git repos: plain `token-goat index .`)
token-goat semantic "how long to steep cold brew"

Returns relevance-ranked, distance-scored hits straight from the notes, the same surgical-read path used for code.

Token savings, measured

Numbers below come from synthetic-fixture benchmarks in the test suite. Each row points at the source file where the measurement is reproduced.

Token-savings examples

Concrete before/after for the four interception points. Token counts use the ~4-chars-per-token rule of thumb.

1. Image — screenshot interception

$ ls -lh screenshot.png
-rw-r--r-- 1 user user 1.2M screenshot.png

# Without token-goat: Claude reads the 1.2 MB PNG.
# With token-goat: hook re-encodes as WebP and substitutes the cached copy.

$ token-goat image-shrink screenshot.png
out: ~74 KB WebP   (94% smaller)

The same image at JPEG quality 85 lands around 120 KB. WebP wins by another ~39% on screenshot-shaped content (large flat regions, sharp text edges).

2. Surgical read — one function, not the whole file

# Without token-goat: full file read.
$ wc -l src/auth.py
512 src/auth.py            # ~12,000 tokens

# With token-goat: pull just the function.
$ token-goat read "src/auth.py::login"
out: 38 lines              # ~300 tokens   (97% smaller)

Same applies to token-goat section "README.md::Install" — one heading instead of the whole document. Anchor IDs and setext headings resolve too, so section "doc.md::Quick-start" works when the file uses Quick start as an <h2> with an explicit {#quick-start} anchor.

3. Compact manifest — preserve what mattered

# Without token-goat: PreCompact fires with no extra context.
# The summarizer LLM picks what to keep, often loses the edit set.

# With token-goat: PreCompact hook injects a structured manifest.
$ token-goat compact-hint --session-id <id>
out: ~280 tokens covering 8 edited files + 12 symbols accessed + 4 key reads

The 280-token manifest is one-shot during compaction. The win is downstream: post-compaction, the agent doesn't re-read files it had already edited, saving a full-file Read pass on each one.

4. Repomap — orientation without an ls -R dump

# Without token-goat: recursive ls + a handful of Read calls to figure out the repo.
$ ls -R . | wc -c
51234                       # ~50 KB of raw paths, no signal about importance

# With token-goat: a ranked orientation summary instead of raw paths.
$ token-goat map --compact
out: ~1 KB                  # top-ranked classes/functions, no locations   (98% smaller)

token-goat map ranks headline symbols by kind (classes/interfaces first) and body size. --compact trims that list to the top 10 symbols (name + kind only, no file/line) and drops the recent-files section, for a denser orientation than the full form.

5. Bash output compression

# Without token-goat: pytest dumps every PASSED line + dots + tracebacks.
$ pytest -v tests/
... (3 KB of output, 150 PASSED lines, 1 FAILED at the bottom)

# With token-goat: the PreToolUse hook rewrites the command to
# `token-goat compress --filter pytest`. The wrapper runs pytest, captures
# stdout+stderr, applies the per-tool filter, and prints failures first.
$ token-goat compress --filter pytest --cmd "pytest -v tests/"
= test session starts =
collected 150 items
FAILED tests/test_x.py::test_one
= 1 failed, 149 passed in 2.3s =

[token-goat: collapsed 149 PASSED lines]
[token-goat: pytest filter compressed 4.8 KiB to 0.1 KiB (97% saved)]

Built-in output compression covers 130+ dev tool CLIs: pytest, jest / vitest, cargo, npm / pnpm / yarn / bun, docker, kubectl / helm, aws, ruff / eslint / mypy / pylint / oxlint, git, make / gradle / mvn / ant / bazel, go test / golangci-lint, terraform / pulumi / cdk, pip / uv / conda, python, gh, ansible, pre-commit, grep, eza / ls, fd, bat, jq, yq, curl / wget, rsync, dotnet, cmake / ctest, swift / xcodebuild, ruby / bundler, elixir / mix, php / composer, flutter / dart, rust / cargo, kotlin / ktlint, zig, crystal, haskell / cabal, nix, R, c++ (conan / vcpkg / cppcheck / clang-tidy), wrangler / hardhat / serverless, erlang, fly.io, forge, elm, julia, tox, vault, packer, nx / lerna / turbo, prettier / biome, sass, wasm-pack, deno, and AI tool CLIs: aider, gemini, claude, gh copilot, copilot, cursor, windsurf (incl. Cascade), opencode, continue, cline. Each filter strips ANSI escapes, collapses \r progress bars, dedupes repeated lines, groups linter issues by rule, keeps every error block verbatim, and caps total output at 1000 lines / 64 KiB. Compound commands (cmd1 && cmd2) are wrapped per segment, so git diff && git log compresses both halves. Disable globally with TOKEN_GOAT_BASH_COMPRESS=0, per-filter via [bash_compress] disabled_filters = ["docker"] in config.toml, or preview the output of any command with token-goat compress --cmd '<your command>'. To exclude project-specific directories from indexing (temporary venvs, build sandboxes), add [indexing] skip_dirs = ["my-tmpdir"] to config.toml. To exclude specific generated files by basename instead (coverage reports, bundler stats), set [indexing] skip_files = [...]; it defaults to ["coverage.json", "coverage-final.json"], so a project with a legitimately-named coverage.json it wants indexed can override the list to drop that entry.

gh api responses get an extra pass: boilerplate *_url fields (followers_url, gists_url, starred_url, and around a dozen others) are stripped from JSON objects; html_url, avatar_url, clone_url, and ssh_url are kept. User and repo objects typically shrink 60–80%. When token-goat sees a GitHub permission error in the output or a non-zero exit on a security endpoint, it injects a system message suggesting gh auth refresh -s security_events.

A failing pytest / jest / vitest / go test / cargo test run (including bare npm test/npm run test/yarn test/pnpm test) also gets a one-line advisory naming the exact token-goat bash-output <id> | token-goat failures command to run instead of re-reading the raw dump. Silent on a passing run, a non-test command, or output too small to be worth reducing.

6. Context pressure

Token-goat tracks how close a session is to the autocompact trigger and tightens its hints as the window fills. Surgical-read suggestions kick in on progressively smaller files as pressure builds (500 lines at cool, down to 50 at critical), so large reads get flagged before they tip the session over. The PreCompact manifest also shrinks: capped at 500 tokens once the window runs hot, 300 once critical, so it stops contributing to the pressure it measures. The denominator is always the fixed 660,000-token autocompact trigger budget, not the model's raw context window, so the same thresholds apply across models. Run token-goat doctor --context to see the current footprint.

For recurring scheduler loops, the 25th, 100th, and 250th observed delivery in a session receive a one-time checkpoint/fresh-session reminder; it prevents further accumulation but cannot reclaim input already injected. The count is independent of the scheduler's bracketed identifier, which some hosts repeat for every delivery. Before a direct test command without a focused selector or explicit timeout, the Bash hook either preserves its existing compressor timeout or gives an advisory when compression cannot apply; it never stops the test.

Install

Easiest install: paste this repo's URL into your AI and ask it to install token-goat properly. It will run the commands, check codecs, and confirm everything is working.

Requirements: Node.js 22 or later (all platforms)

npm install -g token-goat
token-goat install
token-goat doctor          # confirms hooks and sharp are working; look for "sharp: ok"

Three commands. Done. Hooks register and start working immediately; no terminal popups, no tray icon, no service to babysit.

Agents choose the commands

People install token-goat. Agents use it. You do not need to memorize its commands or tell the agent which file type it has.

Installation adds a short routing guide to the agent's instructions. When the agent tries to read a supported binary document, a hook identifies the extension and returns the right next step. The agent starts with an inventory, then reads only the relevant part.

Give the agent the file and the task: “Review manual.pdf for warranty exceptions.” It selects the bounded reader. If no routing rule fits, it can run token-goat commands instead of guessing.

The commands stay separate so every retrieval is visible, repeatable, and easy to narrow. The agent chooses the sequence; the developer can still inspect or run any step directly.

For bounded archive/document comparisons after setup, see the CLI comparison workflow.

Important — sharp is part of the install. The biggest single win (~39% smaller than JPEG, ~97% smaller than raw PNG) comes from WebP encoding. sharp ships with prebuilt native binaries on Windows, macOS, and most Linux platforms, so a standard npm install -g token-goat includes it. On Alpine musl and some ARM boards, npm compiles from source against libvips — that may add a few seconds. token-goat doctor will report sharp: ok when the image pipeline is working; if it flags a failure, follow the Image support section below before considering the install complete. AI agents performing this install: run token-goat doctor after token-goat install and resolve any sharp failure as part of the same task — do not treat it as a follow-up.

Two things change how Claude Code sessions behave: hooks fire automatically (image shrink, re-read dedup, compact manifests), and a delimited routing block written to ~/.claude/CLAUDE.md plus a registered skill gate the agent's reads — before any file read it must ask whether a token-goat read / symbol / section returns just what it needs, and the block explicitly subordinates the harness's own Read/Grep tool-preference rules to the fallback choice once token-goat is ruled out. Install writes no permission entry: whether token-goat commands need a per-call approval prompt is left to your own settings.json, unchanged.

Keep that block where install put it. It's plain markdown in a file you own, so moving it into a tidier reference file is tempting — but install and uninstall resolve one hardcoded path (~/.claude/CLAUDE.md). A relocated copy is never refreshed, so it freezes at whatever version was current when it moved, and the next install sees CLAUDE.md missing its block and appends a fresh one — leaving the guidance duplicated across two files with only one of them live. token-goat doctor warns when it finds a block outside CLAUDE.md, naming the file; install warns at write time and uninstall reports what it couldn't remove. None of them edit a file token-goat doesn't own, so cleanup stays your call. A pointer that merely mentions the markers in prose is fine — detection requires both markers on their own lines.

The background indexer is not started by install. Run token-goat worker start on any platform to launch it as a detached process; token-goat worker status / token-goat worker stop manage it from there.

Companion CLI tools (recommended — install these too)

token-goat covers the narrow-read half of cheap context: pulling one symbol, one section, one cached command output instead of a whole file. It does not cover the deterministic-transform half — searching wide, rewriting code structurally, converting data, running language tooling. Those belong in utilities, not in model output: an operation with a defined algorithm is reproducible, cheaper, and checkable against a spec rather than re-read for plausibility. Install these alongside token-goat so an agent has a real tool for each job instead of burning tokens simulating one.

Priority tier — the three that close actual gaps in a token-goat-only setup:

Base stack — assumed by the read/search guidance token-goat writes into your agent config:

rg (search) · fd (file discovery) · bat (paged/piped reads) · eza (listings) · delta (diff rendering) · jq / yq (JSON / YAML) · sd (find-replace) · mlr (CSV/TSV/JSON records) · sqlite3 (structured queries) · gh (PRs, issues, CI) · hyperfine (benchmarks) · fzf, lazygit (interactive)

Optional but useful: difft (difftastic — syntax-aware diff, so reformats and moved blocks stop generating review noise), just (task runner, keeps verify commands discoverable), typos (deterministic spellcheck).

For archive/document work specifically, token-goat's bounded SQLite, XLSX, and PDF readers are documented in the CLI comparison workflow; keep rendering and schema-specific lineage interpretation in dedicated document tooling.

# macOS / Linux (Homebrew)
brew install ast-grep uv ruff ripgrep fd bat eza git-delta jq yq sd miller sqlite gh hyperfine fzf lazygit

# Debian / Ubuntu — note the binary renames: rg=ripgrep, fd=fdfind, bat=batcat
sudo apt install -y ripgrep fd-find bat jq sqlite3 fzf pipx
pipx install uv && pipx ensurepath     # pipx puts uv in ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"   # this shell; ensurepath covers later ones
uv tool install ruff
npm install -g @ast-grep/cli

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC sharkdp.fd sharkdp.bat eza-community.eza `
               dandavison.delta jqlang.jq MikeFarah.yq chmln.sd Miller.Miller `
               SQLite.SQLite GitHub.cli sharkdp.hyperfine junegunn.fzf JesseDuffield.lazygit
winget install astral-sh.uv        # then: uv tool install ruff
npm install -g @ast-grep/cli       # provides `ast-grep` (the old `sg` alias is deprecated)

If winget is unavailable (common when a session runs under a service account rather than an interactive login), uv also installs via python -m pip install uv, and ast-grep only needs npm. Verify the whole set in one pass:

for t in token-goat ast-grep uv ruff rg fd bat eza delta jq yq sd mlr sqlite3 gh hyperfine; do
  command -v "$t" >/dev/null 2>&1 && echo "$t ok" || echo "$t MISSING"
done

Codex CLI users

token-goat install --codex

The --codex flag patches both Claude Code and Codex CLI in one pass.

Gemini CLI users

token-goat install --gemini

This writes hook entries into ~/.gemini/settings.json using Gemini CLI's BeforeTool / AfterTool / PreCompress event names. Token-goat translates between Gemini's snake_case tool names (run_shell_command, read_file, grep_search, etc.) and its internal format automatically. Image shrinking, session hints, post-edit indexing, compact assist, and bash output compression all work. To remove: token-goat uninstall --gemini.

Qwen Code users

token-goat install --qwen

This writes hook entries into ~/.qwen/settings.json. Unlike Gemini CLI (its own ancestor, with a custom BeforeTool/AfterTool/PreCompress event/matcher scheme), Qwen Code's hooks system diverged and now mirrors Claude Code's own natively — PreToolUse/PostToolUse/PreCompact/UserPromptSubmit/SubagentStop event names and snake_case stdin JSON — so token-goat wires all five events with no wire-format translation needed. Qwen Code's own tool-name taxonomy is only partially documented, so token-goat uses a catch-all matcher per event rather than an incomplete per-tool list. Image shrinking, session hints, post-edit indexing, compact assist, and bash output compression all work. This bridge was built from QwenLM/qwen-code's published docs, not dogfooded against a live Qwen Code install — if hooks aren't firing, token-goat doctor and the settings.json contents are the first things to check. To remove: token-goat uninstall --qwen.

Kimi Code users

token-goat install --kimi

This writes [[hooks]] entries into ~/.kimi-code/config.toml (or $KIMI_CODE_HOME/config.toml), covering Kimi Code's PreToolUse, PostToolUse, PreCompact, UserPromptSubmit, SubagentStop, and SessionStart events. Kimi Code sends a Claude-Code-shaped snake_case payload on stdin, but it reads a different response: only a top-level message and hookSpecificOutput.permissionDecision / permissionDecisionReason. So the install also writes a small shim at ~/.kimi-code/hooks/token-goat-shim.js that translates token-goat's answer into that contract, turns a hint into message, and writes nothing at all for a no-op. Image shrinking, session hints, post-edit indexing, compact assist, and bash output compression all work. Notification and Stop are not wired, because token-goat has no handler for them. Input and output rewriting are not wired either: Kimi Code offers no channel to replace a tool's input or its result. This bridge was built from MoonshotAI/kimi-code's own source and docs, not dogfooded against a live Kimi Code install, so if hooks are not firing, token-goat doctor and the config.toml contents are the first things to check. To remove: token-goat uninstall --kimi.

opencode users

token-goat install --opencode

The --opencode flag patches Claude Code and drops a TypeScript bridge plugin into opencode's plugins directory — one command, no separate base install. Image shrinking, post-edit indexing, and compact assist work. Session hints don't — opencode's plugin API has no way to inject context before a tool read.

openclaw users

token-goat install --openclaw

The --openclaw flag patches Claude Code and registers a TypeScript bridge plugin with OpenClaw's gateway: it drops ~/.openclaw/plugins/token-goat.ts and adds it to ~/.openclaw/openclaw.json's plugins.load.paths / plugins.entries (existing config is merged, never overwritten). OpenClaw's plugin SDK does support before_tool_call/after_tool_call hooks with the block/rewrite shape token-goat needs; unlike the other bridges, no argument-key remapping is needed at all, since OpenClaw's tool-call params are already snake_case (file_path, command, etc.) — the same keys token-goat's own tool_input uses.

What works: bash output compression, re-read denial and surgical-read redirects for oversized first reads, image shrinking, and post-edit indexing (all via before_tool_call/after_tool_call). What doesn't: session hints — OpenClaw's tool-call hooks have no context-injection channel, only param rewriting — and the compaction manifest — OpenClaw's before_compaction/after_compaction are observation-only, with no return-value mechanism to inject a manifest into the next turn the way pi's compaction hooks do.

This bridge has not been validated against a live OpenClaw instance — it's built from OpenClaw's documented plugin SDK and hook event types, not dogfooded against a real running gateway. If tool calls aren't being intercepted, the built-in tool name list in openclaw.ts's TOOL_TO_TG map is the first thing to check. To remove: token-goat uninstall --openclaw.

pi users

token-goat install --pi

The --pi flag patches Claude Code and drops a TypeScript extension into pi's global extensions directory (~/.pi/agent/extensions/token-goat.ts). pi auto-discovers it on the next launch (approve the project-trust prompt the first time). The extension is a normal pi extension — a default-exported factory that subscribes to session_start, tool_call, tool_result, session_before_compact, and session_compact — and bridges those events into token-goat's token-goat hook <event> subprocess protocol.

What works: bash output compression (the bash command is rewritten in tool_call), re-read denial and surgical-read redirects for oversized first reads (both return { block, reason } from tool_call — a confirmed re-read, or a first read at/above the pressure-scaled large_read_redirect_bytes gate, pointing at token-goat skeleton/section/symbol instead), image shrinking (tool_call rewrites the read path in place to a materialized shrunk copy), post-edit indexing and output caching (tool_result), and the compaction manifest (captured at session_before_compact, re-injected after session_compact since pi's compaction replaces rather than appends). Skill-overhead preservation does not apply — pi has no Skill tool; skills are template expansions. To remove: token-goat uninstall --pi.

Project-local install (single project only). pi also loads extensions from a project's .pi/extensions/ directory (after the project is trusted). To install for one project without touching the global directory, drop the extension there:

npx token-goat install --pi --local

This writes .pi/extensions/token-goat.ts in the current project only. Remove it by deleting that file.

Copilot CLI users

token-goat install --copilot

The --copilot flag patches Claude Code and registers a Copilot CLI hook config: ~/.copilot/hooks/token-goat.json (a { version, hooks } file registering sessionStart, preToolUse, postToolUse, preCompact, agentStop, subagentStop, and userPromptSubmitted, per Copilot's own hooks reference) plus the shim script it points at, ~/.copilot/hooks/token-goat-shim.js. Unlike Codex, Copilot's event names and response schema (permissionDecision/modifiedArgs for preToolUse, modifiedResult/additionalContext for postToolUse, decision/reason for agentStop/subagentStop) genuinely differ from Claude Code's, so the shim translates rather than passes through.

What works: the command-routing reminder (sessionStart returns additionalContext, so Copilot is told token-goat exists before it picks its first read tool — this is the one channel that lands ahead of that decision), bash output compression and re-read denial (preToolUse returns modifiedArgs or permissionDecision: "deny"), image shrinking and post-edit indexing (postToolUse returns additionalContext), and stop-hallucination logging (agentStop/subagentStop map a token-goat deny onto decision: "block", everything else onto decision: "allow"). preCompact and userPromptSubmitted are notification-only on real Copilot CLI, per its docs: Copilot never reads a response body for either, so token-goat's compaction manifest and prompt-context hints have no surfacing channel there. The shim still calls through for both so token-goat's internal side effects keep running, but nothing gets injected back into the agent. Copilot's built-in tool names (view, edit, create, bash/powershell, web_fetch, grep, glob, memory, and MCP-server calls) are remapped onto token-goat's internal names where a clear match exists (view→Read, edit→Edit, create→Write, bash/powershell→Bash, web_fetch→WebFetch, grep→Grep, glob→Glob); memory, task, ask_user, and MCP tool calls pass through unmapped and simply no-op.

No ambient environment variable documents "this process is running under Copilot CLI" the way Codex/opencode set one, so the shim sets TOKEN_GOAT_HARNESS_OVERRIDE=copilot_cli itself before calling token-goat hook (same workaround --pi uses). Install also writes a token-goat routing block into ~/.copilot/copilot-instructions.md (the same delimited-block gate written to ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md), merged idempotently so any hand-written content outside the markers is preserved byte-for-byte. If you set COPILOT_HOME, install follows it — hooks go to $COPILOT_HOME/hooks/ and the routing block to $COPILOT_HOME/copilot-instructions.md, matching where Copilot CLI actually reads them. To install for one project instead of user scope: token-goat install --copilot --local (writes .github/hooks/token-goat.json and .github/copilot-instructions.md in the current project). To remove: token-goat uninstall --copilot.

If Copilot CLI starts denying every tool call with Denied by preToolUse hook ... (hook errored): this is Copilot's own fail-closed behavior for a preToolUse hook that crashes, exits non-zero, or returns unparseable output -- it isn't limited to token-goat's own tool calls, since a fail-closed preToolUse hook blocks the whole session. Copilot caches hook configs at session start, so renaming or reinstalling the hook mid-session has no effect -- the only recovery is: run token-goat install --copilot (or token-goat doctor, which now checks the installed hook end-to-end and calls out a stale node-binary path from an nvm/fnm/volta upgrade specifically), then fully restart Copilot CLI.

Grok CLI (xAI Grok Build) users

Grok Build already reads Claude Code's ~/.claude/settings.json as a "Harness Compatibility" source out of the box (confirmed against grok 0.2.93 and its own hooks doc), so token-goat install alone already gets most of the integration working — image shrinking, session hints, post-edit indexing, and bash output compression all fire. The one gap: Grok's own PreToolUse hook contract documents only {"decision":"allow"} / {"decision":"deny","reason":"..."}, never token-goat's harness-independent {"decision":"block","reason":"..."} shape (unlike Gemini CLI, whose docs explicitly confirm "block" as an accepted alias for "deny"), so re-read denial and oversized-first-read redirects don't reliably block on the Claude Code compat path alone.

token-goat install --grok

The --grok flag patches Claude Code and additionally writes a standalone hook config at ~/.grok/hooks/token-goat.json (global scope only — Grok's own project-scoped <project>/.grok/hooks/*.json requires a separate manual /hooks-trust grant this bridge can't perform for you) plus the shim it points at, ~/.grok/hooks/token-goat-shim.js. The shim's only job is translating that one response shape: a token-goat {"decision":"block",...} deny becomes Grok's documented {"decision":"deny",...} (with exit code 2, matching Grok's own "explicit deny" convention), and every other event's response is forwarded through unmodified — Grok already sends the raw camelCase wire payload (toolName/toolInput/sessionId) token-goat's built-in grok harness detection (GROK_SESSION_ID, set on every hook subprocess Grok spawns) already normalizes correctly.

To remove: token-goat uninstall --grok.

Cline, Windsurf, Cursor, and other AI tool CLIs

No separate install step needed. Token-goat compresses the terminal output of these tools automatically as soon as they appear on your PATH. Run token-goat doctor to confirm they are detected — the "Third-party AI tools" section will show detected — bash output compression active.

Filters are built in for: Cline (cline / claude-dev), Windsurf (windsurf, including Cascade AI patterns), Cursor (cursor), GitHub Copilot CLI (gh copilot explain/suggest and the standalone copilot binary — this passive output filter is separate from the --copilot hook bridge above; it works with no install step and covers Copilot CLI's own terminal chrome, not the hook-driven read/index integrations), Aider (aider), Continue (continue), OpenCode (opencode). Each filter strips version banners, spinner/thinking lines, token-usage boilerplate, and tool-call progress noise while keeping the AI response body, error signals, and any user-approval prompts verbatim.

Updating

There is no auto-update mechanism — token-goat never schedules or runs anything on its own. Updating is always a manual npm install -g token-goat@latest.

Upgrading from the Python version

The old Python package (pip install token-goat) wrote hook entries into settings.json with commands containing token_goat (underscore), invoking Python directly: something like pythonw.exe -m token_goat.cli hook pre_tool_use. The npm package invokes a generated shim instead ("<node>" "~/.claude/hooks/token-goat-shim.js" pre_tool_use "<entry>").

Both install and uninstall recognize the older command spellings — token_goat, tokenwise, tg-hook, token-goat-hook, and the pre-shim token-goat hook — so you do not need to hand-edit settings.json. Installing replaces a stale entry in place rather than leaving a dead one beside the new one, and uninstalling removes it.

To upgrade cleanly:

1. Remove the Python package: pip uninstall token-goat
2. Install and register the npm package: npm install -g token-goat && token-goat install
3. Verify: re-run token-goat install, which should now report hooks already up to date, or use the jq check under Verify.

AI agents handling an upgrade: complete all three steps in sequence. After step 3, confirm no token_goat entries remain in settings.json before reporting the upgrade done.

CLI

Every command accepts a global --cwd <path>, which runs it as if invoked from that directory. It exists so a caller can name a project root without making that root its own working directory — a launcher should never resolve a binary name against a directory the workspace controls. It is applied before anything resolves the project root or loads config, so --cwd selects which .token-goat.toml applies.

Archive/document comparison workflow

These are agent-selected primitives, not a manual checklist. Give the agent the file and the question. The installed routing guide and read hook select the matching format flow; the commands below show the steps it can take without loading whole files:

token-goat sqlite-schema catalog.db
token-goat sqlite-query catalog.db "SELECT file_path, name FROM files WHERE name LIKE '%owner%' LIMIT 20" --json
token-goat xlsx-sheets link-map.xlsx
token-goat xlsx-query link-map.xlsx --sheet Links --columns publication,source,target --head 50
token-goat pdf-meta manual.pdf
token-goat pdf-outline manual.pdf
token-goat pdf-extract manual.pdf --pages 12-15 --layout --head 120

token-goat intentionally does not render PDF pages or infer XML publication lineage: those operations produce binary/visual output or require schema-specific interpretation. Keep those steps in the document/PDF tooling, then pass only the bounded paths, rows, and page text needed for comparison.