Token-Goat CLI
Token-Goat trims repeated file reads, build noise and heavy screenshots before they reach an agent's context window.
- 148 ★ on the repository
- Last commit
Extended access
Why this level
- Hooks intercept file reads and command output and change what the model receives.
- Installation edits agent configuration and builds a local project index.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/token-goatDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Hooks intercept file reads and command output and change what the model receives.
- Installation edits agent configuration and builds a local project index.
This is third-party code. Review the repository files before installing.
What it does
Token-Goat installs hooks into Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, Windsurf and other agents and cuts token use without changing habits. A repeat file read becomes a hint with a narrow slice, `pytest`, `npm install` or `docker build` output shrinks to the errors, a screenshot drops to about a hundred kilobytes. PDFs, Office files and CSVs are intercepted so the model gets structure instead of the whole file. The `token-goat read "file::symbol"` and `token-goat brief` commands return one function with its callers instead of paging through a file. Before a session is compacted, a manifest of edited files and key symbols is added. The same set runs as an stdio MCP server with `token-goat mcp-serve`. Fetched pages and tool results are wrapped in an untrusted-content fence against prompt injection.
Who it is for. Developers with long Claude Code or Codex sessions who worry about token bills and context lost after compaction.
Good fit when
- Sessions run for hours while the agent re-reads the same files.
- Builds and tests flood the context with progress bars and lists of passing tests.
- Screenshots and PDFs weigh megabytes and eat the model window.
- You want one set of savings rules across several agents at once.
Not a fit when
- The agent runs in a mode without hook support, and MCP mode does not cover every scenario.
- The project is commercial: the PolyForm Noncommercial license forbids commercial use.
- The model needs every byte of command output uncompressed.
Example request
Show the body of `parseConfig` from `src/config.ts` with its callers without reading the whole file.Limitations
The PolyForm Noncommercial license requires separate permission from the author for commercial work. The README marks macOS as untested and lists Windows and Linux, including WSL, as the main platforms. Node.js is required. Hooks change what the model sees, so when debugging odd agent behavior turn compression off with `TOKEN_GOAT_BASH_COMPRESS=0`. Savings figures in the README are the author's; measure on your own sessions with `token-goat stats`.
How to disable. Remove the hooks and config entries following the security and uninstall section in `docs/security.md`, then run `npm uninstall -g token-goat`. The index and cache in the data directory are deleted separately.
FAQ
What exactly gets installed?
Hooks and an instruction block in agent configs, plus an index, cache and models in a data directory. The full list is in `docs/install.md` under What gets installed.
How do I connect it to Cursor?
Run `token-goat install --cursor`: the server is registered in `~/.cursor/mcp.json`. The `-p` flag writes it to the project.
Which MCP tools are on by default?
Seven: `symbol`, `read`, `section`, `outline`, `semantic`, `refs` and `retrieve_text`. Others are enabled by a list in `TOKEN_GOAT_MCP_TOOLS`.
How do I turn off command output compression?
Set `TOKEN_GOAT_BASH_COMPRESS=0`. Output is still cached, so `bash-output` keeps working.
Under which license is it distributed?
PolyForm Noncommercial. Noncommercial use is allowed; commercial work needs the author's permission.
Discussion
No questions or reviews yet.
Related
CLI toolsToken-Saver compresses terminal output for Claude Code: diff, pytest, npm, terraform, kubectl, docker. Compression runs locally.
Claude Token Optimizer: fewer tokens at startup
Claude Token Optimizer
The cto utility counts the tokens Claude Code loads at session start and shrinks CLAUDE.md into a short cheat sheet.
Local code search for agents: finds the files and fragments that matter and keeps context within a set token budget
A Go CLI proxy that shrinks git, test and build output with YAML filters before it reaches the agent. The author estimates 60-90% token savings
Local dashboard for tokens, cost and tool calls across Claude Code, Codex, Gemini CLI and many other coding agents.
Token Router pulls needed original lines from big logs and Python files, so the model reads less and sees no paraphrase.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Token-Goat (this card) | no | 148 | ||
| Token Optimizer | no | 2,964 | a token optimization plugin; Token-Goat uses hooks across several agents and compresses output of over 150 CLIs | |
| TokenSave | yes | not required | 704 | an MCP server; this one also intercepts reads, compresses output and keeps a compaction manifest |
README in short
Installation writes hooks and a command routing block into the agent instructions, and the agent picks the right command itself: a surgical read, a search, a repository map or recall of output it already has.