Ecotokens

ecotokens saves real AI coding context

On one developer workstation, ecotokens recorded 19 928 hook executions between 2026-03-06 and 2026-05-27. The result: 94 282 087 tokens before filtering, 5 874 896 tokens after filtering, and 88 407 191 tokens saved. That is a 93.8% overall reduction across real shell commands and native tool results.

| Real-world metric | Value | |-------------------|------:| | Hook executions measured | 19 928 | | Tokens saved | 88 407 191 | | Overall reduction | 93.8% | | Commands with savings | 5 735 / 19 928, or 28.8% | | Biggest command family | grep, with 55 383 168 tokens saved |

Claude Code, Gemini CLI, Qwen Code, Pi, Hermes, and Codex can all dump massive command outputs and native tool results into your context window. ecotokens sits in front of those outputs, removes the noise, preserves the important bits, and records the before/after savings locally.

Built on a "set it and forget it!" philosophy: one install command, zero configuration, then automatic compression for shell commands, file reads, grep/search results, directory listings, and code-intelligence workflows.

Full methodology and per-family breakdown: [docs/BENCHMARKS.md](docs/BENCHMARKS.md).

Features highlight

| Feature | Details | |---------|---------| | PreToolUse hook | Intercepts every shell (Bash) command before its output reaches the model - filters, compresses, and records savings | | PostToolUse hook | Intercepts native tool results (Read/read_file, Grep/search_file_content, Glob/list_directory) - outline-based compression for source files, grep trimming, glob denoising | | Gain dashboard | Interactive TUI - token savings by command family or project, sparkline, diff view, history log | | Multi-agent support | Works with Claude Code, Gemini CLI, Qwen Code, Pi, Hermes, and Codex out of the box | | Precision guarantees | Errors, failures, and stack traces are never removed; secrets are redacted before filtering | | Code intelligence | BM25 + vector search (Candle zero-config or Ollama), symbol lookup, call graph tracing, near-duplicate detection | | MCP server | Exposes code-intelligence tools over stdio (ecotokens mcp-server) and auto-registers in agent settings on install | | AI summarization (optional) | Large outputs compressed by a local Ollama model instead of being truncated | | Word abbreviations (optional) | Replace common words with shorter forms (function→fn, configuration→config, …) in narrative text, and nudge the model to do the same via a SessionStart instruction | | Zero config | One ecotokens install command - works automatically from there |

> Full compatibility matrix: [harness feature matrix](docs/harness-feature-matrix.md)

How it works

ecotokens installs hooks that intercept tool outputs before they reach the model. Two interception points are supported:

PreToolUse / BeforeTool - fires before every shell (Bash) command:

1. Runs the command and captures its output
2. Applies a family-specific filter (git, cargo, python, …)
3. Optionally summarizes large outputs via a local AI model (Ollama)
4. Returns the compressed output to the model
5. Records the before/after token counts in a local metrics store

PostToolUse / AfterTool (Claude Code, Gemini CLI, Qwen Code) - fires after native file-tool calls:

1. Intercepts the tool result before it enters the context window
2. Applies a specialized filter (outline for source files, grep result trimming, glob path denoising)
3. Returns the compressed result to the model
4. Records the savings under the native_read, grep, or fs family

Claude Code uses the PreToolUse + PostToolUse hooks (~/.claude/settings.json). Gemini CLI uses the BeforeTool + AfterTool hooks (~/.gemini/settings.json). Qwen Code uses the PreToolUse + PostToolUse hooks (~/.qwen/settings.json). Pi uses a TypeScript extension (~/.pi/agent/extensions/ecotokens.ts) that intercepts tool_call (bash pre-exec) and tool_result (read/grep/find/ls post-exec) events in-process. Hermes uses a plugin that sends outputs through filter-output via HermesTransformTerminalOutput and HermesTransformToolResult hook types. Codex uses PreToolUse + PostToolUse hooks in ~/.codex/hooks.json and registers the MCP server in ~/.codex/config.toml.

For a focused view of the runtime path, see [docs/hook-filter-metrics-flow.md](docs/hook-filter-metrics-flow.md).

The result: the model sees clean, concise output - and you keep your context window.

Quick install

cargo install --git https://github.com/hansipie/ecotokens

For exact token counting (tiktoken cl100k_base instead of the character heuristic):

cargo install --git https://github.com/hansipie/ecotokens --features exact-tokens

Build from source

git clone https://github.com/hansipie/ecotokens.git
cd ecotokens
cargo build --release
./target/release/ecotokens --help

To install the locally built binary into Cargo's bin directory:

cargo install --path .

With exact token counting enabled via tiktoken (cl100kbase encoding):

cargo install --path . --features exact-tokens

By default, token counts use a fast character heuristic (chars × 0.25, ~80-85% accuracy). This has no effect on filtering behavior - only the token counts recorded in metrics are more precise.

Installation

> Ready-to-copy configuration snippets for all supported integrations: [docs/example-configs.md](docs/example-configs.md).

Claude Code

cargo install --path .
ecotokens install

Install commands print a section per target, followed by the entries that were written:

Install Claude Code
  ok      hook                   ~/.claude/settings.json
  ok      post-hook              ~/.claude/settings.json
  ok      MCP server             ~/.claude/settings.json

In addition to hook installation, this also registers an MCP server entry in ~/.claude/settings.json:

{
  "mcpServers": {
    "ecotokens": {
      "command": "ecotokens",
      "args": ["mcp-server"]
    }
  }
}

Gemini CLI

Requires Gemini CLI ≥ 0.1.0.

cargo install --path .
ecotokens install --target gemini

This writes BeforeTool and AfterTool hook entries into ~/.gemini/settings.json. The AfterTool hook intercepts read_file, search_file_content, and list_directory results.

It also registers the ecotokens MCP server in ~/.gemini/settings.json.

Qwen Code

Requires Qwen Code.

cargo install --path .
ecotokens install --target qwen

This writes PreToolUse and PostToolUse hook entries into ~/.qwen/settings.json. The PostToolUse hook intercepts read_file, search_files, and list_dir results.

It also registers the ecotokens MCP server in ~/.qwen/settings.json.

Pi

Requires Pi (@mariozechner/pi-coding-agent ≥ 0.62.0).

cargo install --path .
ecotokens install --target pi

This writes a TypeScript extension to ~/.pi/agent/extensions/ecotokens.ts. Pi auto-discovers it on next startup (or /reload inside an active session). The extension intercepts bash commands before execution and filters native tool results (read, grep, find, ls) after execution.

Hermes

Requires Hermes.

cargo install --path .
ecotokens install --target hermes

This installs an ecotokens plugin in ~/.hermes/plugins/. The plugin intercepts two Hermes hooks:

• transform_terminal_output — filters raw terminal output before Hermes truncates it
• transform_tool_result — filters non-terminal tool results (read_file, search_files, browser_snapshot, MCP tools, etc.)

Each hook calls ecotokens filter-output as a subprocess with the appropriate --hook-type, so savings are tracked separately in ecotokens gain.

Enabling the plugin — Hermes requires explicit activation. Two options:

# Option A: via Hermes CLI (requires hermes to be installed and in PATH)
hermes plugins enable ecotokens

# Option B: write directly to ~/.hermes/config.yaml (no hermes CLI needed)
ecotokens install --target hermes --enable-plugin

--enable-plugin adds ecotokens to plugins.enabled in ~/.hermes/config.yaml, creating the file if it does not exist and preserving all existing keys. Restart Hermes after enabling.

Per-tool filtering — tool result labels (hermes-tool:) are mapped to the appropriate filter family automatically:

| Tool | Family | Filter applied | |------|--------|---------------| | read_file, list_directory, create_file | fs | file listing compaction | | search_files, find_files, search_in_file | grep | match deduplication | | browser_snapshot, web_fetch, web_search | network | HTML/JSON reduction | | run_python_code, execute_python | python | traceback extraction | | delegate_task, MCP tools, others | generic | 200-line / 50 KB cap |

Runtime variables — the generated plugin reads these from the environment:

| Variable | Default | Effect | |----------|---------|--------| | ECOTOKENS_BIN | path at install time | Override the ecotokens binary called by the plugin | | ECOTOKENS_HERMES_MIN_CHARS | 2000 | Skip filtering outputs shorter than this | | ECOTOKENS_HERMES_TIMEOUT | 10 | Subprocess timeout in seconds |

The plugin is fail-open: any error, timeout, or empty output returns the original content unchanged.

Codex

cargo install --path .
ecotokens install --target codex

This installs three things:

• Plugin (~/.codex/plugins/ecotokens/.codex-plugin/plugin.json) — identifies ecotokens to Codex
• Hooks (~/.codex/hooks.json) — PreToolUse (bash pre-exec filtering) and PostToolUse (bash post-exec filtering)
• MCP server (~/.codex/config.toml) — registers ecotokens mcp-server under [mcp_servers.ecotokens]

All targets at once

ecotokens install --target all

--target all covers Claude Code, Gemini CLI, Qwen Code, Pi, Hermes, and Codex in a single command.

With AI summarization

Enable AI-powered output compression via Ollama at install time:

ecotokens install --ai-summary                          # use default model (llama3.2:3b)
ecotokens install --ai-summary-model qwen2.5:3b         # specify model (implies --ai-summary)

This writes ai_summary_enabled and ai_summary_model to ~/.config/ecotokens/config.json. Ollama must be running and the model must be pulled (ollama pull llama3.2:3b).

Uninstall

ecotokens uninstall                    # Claude Code
ecotokens uninstall --target gemini    # Gemini CLI
ecotokens uninstall --target qwen      # Qwen Code
ecotokens uninstall --target pi        # Pi
ecotokens uninstall --target hermes    # Hermes
ecotokens uninstall --target codex     # Codex
ecotokens uninstall --target all       # all targets

Uninstall commands use the same grouped output and only list entries that were present:

Uninstall Claude Code
  removed hook                   ~/.claude/settings.json
  removed post-hook              ~/.claude/settings.json
  removed MCP server             ~/.claude/settings.json

If nothing is installed for the selected target, the command prints:

Uninstall Claude Code
  note    nothing to uninstall

Commands

| Command | Description | |---------|-------------| | ecotokens install | Install the PreToolUse + PostToolUse hooks and register the MCP server entry in ~/.claude/settings.json | | ecotokens install --target hermes | Install the Hermes plugin in ~/.hermes/plugins/ | | ecotokens install --target hermes --enable-plugin | Install and add to plugins.enabled in ~/.hermes/config.yaml directly | | ecotokens install --target codex | Install the Codex plugin, PreToolUse/PostToolUse hooks in ~/.codex/hooks.json, and MCP server in ~/.codex/config.toml | | ecotokens uninstall | Remove all hooks (PreToolUse, PostToolUse, SessionStart, SessionEnd where supported) and the MCP server entry | | ecotokens filter -- CMD [ARGS] | Run a command, filter its output, record metrics | | ecotokens filter --cwd DIR -- CMD [ARGS] | Same, with an explicit working directory | | ecotokens filter-output --command LABEL --exit-code N | Filter captured output read from stdin and record metrics (used by Hermes hooks) | | ecotokens filter-output ... --hook-type transform-tool-result | Same, attributed to the transform_tool_result hook in metrics | | ecotokens hook-post | PostToolUse handler - intercept native tool results (Read, Grep, Glob) | | ecotokens gain | Interactive TUI dashboard - savings by family or project | | ecotokens gain --period PERIOD | Filter TUI to a time window (all, today, week, month) | | ecotokens gain --history | Print a savings summary table for 24h / 7 days / 30 days | | ecotokens gain --json | JSON report | | ecotokens config [--debug true\|false] | Show or update global configuration (including debug mode) | | ecotokens doctor [--json] | Diagnose PATH, config, hook, MCP, and metrics setup without mutating files | | ecotokens config --model MODEL | Set the default model used for cost calculations (empty or unknown value lists available models) | | ecotokens config --embed-provider candle\|ollama\|none | Set the embedding backend (candle = local BERT, ollama = Ollama HTTP API, none = BM25 only) | | ecotokens config --embed-model MODEL | Set the embedding model (e.g. qwen3-embedding:latest for Ollama, or a HuggingFace ID for Candle) | | ecotokens config --embed-url URL | Set the Ollama base URL (default: http://localhost:11434) | | ecotokens index [--path DIR] | Index a codebase for BM25 + symbolic search | | ecotokens search QUERY [--context N] [--include GLOB] [--exclude GLOB] [--no-trace] | Search the indexed codebase with line numbers, context, and optional trace augmentation | | ecotokens outline PATH | List symbols in a file or directory | | ecotokens symbol ID | Look up a symbol by its stable ID | | ecotokens trace callers SYMBOL | Find callers of a symbol | | ecotokens trace callees SYMBOL | Find callees of a symbol | | ecotokens watch [--path DIR] | Watch a directory and keep the index up to date | | ecotokens mcp-server [--index-dir DIR] | Start the stdio MCP server exposing search/outline/symbol/trace/duplicates tools | | ecotokens auto-watch enable | Start watch automatically on each Claude Code, Qwen Code, Pi, Hermes or Codex session | | ecotokens auto-watch disable | Disable automatic watch | | ecotokens abbreviations enable | Replace common words with abbreviations in filtered outputs + inject a matching instruction at SessionStart | | ecotokens abbreviations disable | Turn abbreviations off (default) | | ecotokens abbreviations list | List the active dictionary (defaults merged with user overrides) | | ecotokens duplicates | Detect near-duplicate code blocks in the indexed codebase | | ecotokens clear --all | Delete all recorded interceptions | | ecotokens clear --before DATE | Delete interceptions recorded before DATE (YYYY-MM-DD) | | ecotokens clear --older-than DURATION | Delete interceptions older than a duration (e.g. 30d, 2w, 1m) | | ecotokens clear --family FAMILY | Delete interceptions of a specific command family | | ecotokens clear --project PATH | Delete interceptions for a specific project (use "[undefined]" for entries without a git root) | | ecotokens completions SHELL | Generate a shell completion script (bash, zsh, fish, powershell, `elvish

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hansipie
• Source: hansipie/ecotokens
• License: MIT

Install and usage instructions live in the source repository linked above.