Gemini CLI · Updated 2026-10-09
Reduce Gemini CLI Token Usage: Compress Tool Output
Gemini CLI can read a lot at once, which makes it easy to fill a session with whole files and long command output. Here is where Gemini CLI tokens go and how SuperCompress lets the agent keep only the lines that answer your question.
/stats to watch usage, /compress or /clear when a session gets long, and keep GEMINI.md short. Then run npm install -g supercompress-proxy && supercompress setup to add the SuperCompress MCP server to Gemini CLI.
Where Gemini CLI tokens go
- File reads. Reading whole files or folders brings everything in at once.
- Shell output. Full test and build logs.
- MCP servers. Tool definitions plus results.
- Context files.
GEMINI.mdfiles are loaded into the session.
Habits that cut Gemini CLI token usage for free
- Check usage.
/statsshows token use for the session. - Compress or clear long sessions.
/compressreplaces the history with a summary;/clearstarts over. - Read narrowly. Point at the files you mean instead of whole directories.
- Keep
GEMINI.mdshort. It is loaded every session. - Only enable the MCP servers you use.
These habits shrink what goes in. They don't help when the agent genuinely needs to run a test suite or read a large file and only a few lines of the output matter. That is the part SuperCompress handles.
How SuperCompress works
SuperCompress is hosted, extractive and query-aware. Your agent sends a large block of context (a log, a diff, a file read, an MCP result) together with the question it is working on. Our Neural Keep model scores the lines against that question, keeps the original lines that answer it, and drops the rest. It never rewrites or summarizes, so file paths, error messages, IDs and code come back exactly as they were. The question itself is never compressed.
Every compress call reports original_tokens and kept_tokens, so you can see what was dropped on your own work instead of trusting a headline number. The usage_summary MCP tool shows totals per agent for your account.
What supercompress setup adds to Gemini CLI
| What | Where | What it does |
|---|---|---|
| MCP server | ~/.gemini/settings.json (mcpServers.supercompress) | Gives the agent the compress_context, connect_account and usage_summary tools. |
Install
npm install -g supercompress-proxy && supercompress setupSetup links your SuperCompress account in the browser, detects the coding agents on the machine and wires each one. Restart the agent so it loads the new MCP server. Then check what is wired up:
supercompress doctordoctor prints a per-agent health check. supercompress uninstall removes only the entries SuperCompress added. Setup backs up each config file before it edits it.
How this differs from /compress
Gemini CLI's /compress summarizes the whole history in its own words. SuperCompress works on one bulky result at a time and keeps original lines, so exact errors, paths and code survive. Use both: SuperCompress on large new output, /compress when the session itself gets long.
When to skip it
- Short sessions with small tool results. There is little to drop.
- Files the agent is about to edit line by line. It needs those in full.
- Work where every byte must be passed through unchanged for compliance reasons.
FAQ
Does SuperCompress change how I sign in to Gemini CLI?
No. You keep your normal Gemini CLI login and models. SuperCompress adds an MCP server and instructions to Gemini CLI; it does not route Gemini CLI's model traffic through a proxy.
Does SuperCompress summarize what Gemini CLI reads?
No. It is extractive. The lines it keeps are copied from the original output, so file paths, error messages and code stay exactly as they were.
How do I undo the Gemini CLI setup?
Run supercompress uninstall. It removes only the entries SuperCompress added, so your other MCP servers, hooks and instructions stay as they were.