kompactor 0.8.6

Cut the tokens Claude Code spends on noise.
Shorter tool output for Claude, the same answers, and a dashboard that shows what every turn saved.

Quick start · How it works · Evidence · Configuration · FAQ

Most of a Claude Code session's tokens aren't your prompt or Claude's answer. They're tool output: test runs, installs, git log, whole-file reads. That output is sent again on every later turn until the context is compacted. Kompactor shrinks it before Claude reads it, and always keeps errors, failing tests, your own stack frames and summary lines.

Measured in 54 real Claude Code sessions on Flask, Cobra, SWR, ky and zustand at the default level. Single commands shrink far more: a failing pytest -v run goes from 9,842 to 1,138 tokens, and a fresh npm install from ~33,000 to 469. See the evidence.

Contents

• Features
• Quick start
• How it works
• Examples
• Usage
• Levels
• Configuration
• See your savings
• Code graph
• Use it across a team
• Evidence
• Supported languages
• What Kompactor runs and changes
• Troubleshooting
• FAQ
• Development
• Contributing
• License

Features

• Compacts command output. Passing tests, progress bars, download chatter, library stack frames and lock-file diffs are dropped. Errors, failures, your own frames and summary lines are always kept.
• Handles failing commands. Claude Code skips output hooks when a command fails and cuts its output to the first and last ~5K characters. Kompactor's shell prefix runs the command to completion, compacts it and passes the exit code through.
• Outline-first file reads. Big source files arrive as an outline (symbols, line ranges, who imports the file, which tests cover it). Claude reads just the ranges it needs; repeating the read returns the whole file.
• Local code graph. Find code by topic, see callers, the impact of a change and the tests to run, for Python, Go, TypeScript, JavaScript, React, Rust, Java, Kotlin, Scala, C#, Swift, C, C++, Ruby and PHP.
• Terse replies and lean code. Short, readable rules for answer-first prose and smallest-diff code, from 0 to 177 tokens depending on the level.
• Per-turn savings, in tokens and dollars. In the reply, the status line, a VS Code / Cursor sidebar (per session, per project and per turn) and a local dashboard. Numbers are conservative and never count output Claude wouldn't have read.
• One dial for quality vs tokens. Five levels, every option adjustable, per project, and a line-by-line before and after of what Claude actually got.
• Nothing is lost. Every shortened output keeps a raw copy (kompactor show <id>), and every hook fails open.
• Private and dependency-free. Python 3.9+ standard library only. Runs locally, sends nothing anywhere, no telemetry.
• Proven, reproducibly. kompactor prove reruns real Claude Code tasks with and without Kompactor; the results are in this repo.

Quick start

Pick one. All of them set up the same thing, and the Claude Code CLI and VS Code extension share it.

Claude Code plugin (recommended). In any Claude Code session, one line at a time:

/plugin marketplace add amarkum/kompactor
/plugin install amarkum@kompactor
/kompactor start

The last step turns Kompactor on: it adds the status line and the shell prefix that compacts failing commands (a plugin can't set those itself) and opens the dashboard. Then restart Claude Code.

pip / pipx / uv (macOS, Linux, Windows):

pipx install kompactor        # or: pip install kompactor · uv tool install kompactor
kompactor start

If your shell says kompactor: command not found (pip put the command in a folder that isn't on your PATH), run python3 -m kompactor start once. It links kompactor into a folder that is already on your PATH, such as ~/.local/bin, so the command works in every terminal from then on.

VS Code and Cursor. kompactor start adds the Kompactor extension to VS Code and Cursor automatically when they're installed (skip it with --no-editor); reload the window and a Kompactor icon appears in the activity bar. To install it by hand, download kompactor-0.8.6.vsix from Releases and use Extensions › ⋯ › Install from VSIX….

From source:

git clone https://github.com/amarkum/kompactor.git && ./kompactor/install.sh     # Windows: .\kompactor\install.ps1

After you install

1. Restart Claude Code (CLI or VS Code). Kompactor starts with the next session.
2. Work as usual. You don't call Kompactor; it acts on Claude's tool calls by itself. After each reply you'll see a line like Kompactor: −8.2k tokens this turn, and the status line shows the running total.
3. Check it's on: run kompactor in a terminal (or /kompactor in Claude Code):

   Kompactor 0.8.6 is on
   
     Claude Code   connected
     Level         Balanced (3 of 5)
     Saved         41.3k tokens (−38%) in 52 tool calls
     Dashboard     http://127.0.0.1:56710/
   

   kompactor help lists every command.
4. In VS Code or Cursor: click the Kompactor icon in the activity bar for tokens and dollars saved this session, in this project, today and over 30 days, plus what Kompactor shortened in each of Claude's recent replies.
5. Three commands to remember: kompactor start turns it on and opens the dashboard, kompactor stop pauses it, kompactor uninstall removes it.

How it works

Kompactor uses Claude Code's hooks, so it sits between Claude's tools and Claude itself:

Nothing is lost. Every shortened output keeps a raw copy that Claude can fetch with kompactor show <id> (the id is printed in the short version). An outline-first read is "deny once, allow on retry", so Claude can always get the full file. Kompactor never changes what a command does, your permission rules still apply, and every hook fails open. How Claude Code's hooks behave on success, failure and very long output is written up in docs/SPEC.md.

Examples

Ask Claude Code the way you normally would. These prompts come from the evidence runs:

Usage

In Claude Code

In a terminal

Levels

One level sets everything. Change it on the dashboard, with /kompactor <level> in chat, or with kompactor config preset <1-5>. Each project can have its own level.

Where the saving comes from. Every request re-sends the whole conversation, so on a 1M-context model most of a long session's cost is the conversation being read again (80% of it in the sessions measured). Trimming tool output helps a little; letting the conversation grow less before Claude Code compacts it is what moves the bill. Each level sets Claude Code's own autoCompactWindow while Kompactor is on. The trade-off: after a compaction Claude keeps a summary of the early part of the session, not every detail, so higher levels compact more often (in the sessions measured, 7 extra compactions at Quality and 74 at Max savings, over 65 sessions). A window you set yourself with /autocompact always wins, kompactor stop puts Claude Code's default back, and Claude Code caps the window at each model's own size, so 200K-context models are unaffected.

* 65 real Claude Code sessions on Opus 5.5 (1M context), replayed at each level with kompactor estimate: output trimming plus compacting earlier, with an 8K-token summary per compaction. Not counted: files Claude re-reads after a compaction. Your figures depend on how long your sessions run; the Configuration page shows each level's estimate on your own sessions.

Configuration

Settings come from, in increasing priority: the level → your global choices → a committed .kompactor.json in the repo → your per-project choices on the dashboard → KOMPACTOR_<SETTING> environment variables → KOMPACTOR_PRESET. The dashboard is the easiest way to change them; kompactor config prints the effective settings for the current folder.

Settings

General: turn_summary (savings line after each reply), statusline, retention_days (default 30).

Environment variables

Per-repository settings

Commit a .kompactor.json next to the code to give everyone the same level and overrides:

{ "preset": 4, "overrides": { "never_compact": ["terraform plan"] } }

See your savings

The numbers are conservative: they count only what Claude would really have read. When Claude Code would have truncated an output anyway, only the truncated size counts, and when Claude reads a whole file after its outline, the outline's saving is reversed.

Code graph

A local index of your repository: functions, classes, imports and calls, plus the sections of your Markdown and reStructuredText docs and the code they mention, so impact and explain also name the docs to update. It builds in about a second (Flask: 84 files in 0.35 s), refreshes in the background after edits, and is never sent anywhere or written into your repo. Claude uses it on its own; you can query it too:

kompactor graph query "session cookie"     find code by topic, with line ranges and who uses it
kompactor graph impact createStore         what uses it, and which tests to run
kompactor graph explain Name               one symbol: signature, callers, callees, tests
kompactor graph callers / deps / path      who calls it, what it imports, how two modules connect
kompactor graph report                     core modules, entry points, communities, import cycles
kompactor graph unused                     dead-code candidates
kompactor graph export json|graphml|mermaid  the graph as data, for Gephi/yEd, or as a diagram (--out FILE)
kompactor graph export obsidian --out DIR  an Obsidian vault: a note per module, linked by imports
kompactor graph hook install               refresh the graph after each commit, merge and checkout

Use the graph from any MCP client

kompactor mcp serves the graph over the Model Context Protocol (stdio), so Cursor, Codex, Gemini CLI, Windsurf or a second Claude Code setup can use it too. Its tools are read-only: graph_query, graph_callers, graph_impact, graph_deps, graph_explain, graph_path, graph_report, graph_unused, outline and symbol. The graph is refreshed (only changed files) before each answer, and paths outside the project are refused.

claude mcp add kompactor -- kompactor mcp

Other clients take the same command in their MCP settings, for example {"mcpServers": {"kompactor": {"command": "kompactor", "args": ["mcp"]}}}. Add --root <folder> to serve a project other than the folder the client starts it in.

Use it across a team

Turn it on for everyone who works in a repo. Commit this as .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "kompactor": { "source": { "source": "github", "repo": "amarkum/kompactor" }, "autoUpdate": true }
  },
  "enabledPlugins": { "amarkum@kompactor": true }
}

When a teammate trusts the folder, Claude Code installs the plugin; each person then runs /kompactor start once. autoUpdate keeps everyone on the latest release. Admins can put the same keys in Claude Code's managed settings to roll it out to every machine, and a team that runs its own fork sets KOMPACTOR_REPO so the dashboard shows the fork's commands.

Teammates on other coding agents. kompactor rules writes the same reply and code rules, plus how to use the code graph, into each agent's own rules file: .cursor/rules/kompactor.mdc (Cursor), .windsurf/rules/kompactor.md (Windsurf), .clinerules/kompactor.md (Cline), and a marked block in AGENTS.md (Codex and others), .github/copilot-instructions.md (GitHub Copilot), GEMINI.md (Gemini CLI) and CONVENTIONS.md (Aider). --agent cursor picks one; running it again updates the block in place; --remove takes it out and leaves the rest of each file alone. Those agents can also query the graph through kompactor mcp.

Evidence

kompactor prove runs each task in real headless Claude Code sessions (claude -p), 3 times without Kompactor and 3 times with it, interleaved, with the same prompt, tools, turn limit and budget cap. Tokens are input + cache writes + cache reads + output across every API call; cost is Claude Code's own figure.

At the other levels, against the same baseline:

Single commands, measured directly (bench/bench.py):

• The wins come from avoided turns. Every turn re-sends the whole context. The vitest failure was 32K characters of passing tests; Kompactor gave Claude 1K characters with the failure, at 37% lower cost.
• Short sessions pay a small fixed cost. On 2-turn tasks with little output, the rules add about 1%.
• Session savings are smaller than command savings because most of each session is Claude Code's own fixed context.

Read more: full report · every session's tokens, tool calls and answers · what Claude received in each arm for the same failing run · how Kompactor compares with graphify, rtk, caveman and others

Reproduce it: python -m kompactor prove --tasks bench/tasks.json --repos <folder with the bench repos> --reps 3

Compaction on real repositories. evidence/real-repos runs real test suites, builds, git log/git diff and grep in 6 repositories (Python, TypeScript, C, Swift, Java) and plants one failure in each failing run: a median −61% per output at Balanced, and every planted failure line reached Claude at levels 1, 3 and 5. Outputs Claude Code would otherwise save to a file and preview in 2 KB are given in full, compacted, so on those Kompactor can cost more than the preview while handing over the actual results; the report shows both baselines.

Supported languages

Command output from any language is compacted. These languages also get language-aware trimming, outlines and the code graph; Kompactor detects them per repo (pyproject.toml, go.mod, tsconfig.json/package.json, a react or next dependency).

More languages, detected per repo the same way:

Test files are recognised for each (*Test.java, *_spec.rb, tests/, CartTests.swift and so on), so impact names the tests to run.

What Kompactor runs and changes

Everything below happens on your machine. Kompactor makes no network requests of its own and has no telemetry. (If you install the optional tiktoken package for exact token counts, tiktoken downloads its token table once, on first use.)

What it runs. Python hooks that Claude Code calls (python3 kompactor/_launch.py hook <name> from the plugin folder): after Bash, Read, Grep, Glob and edit tool calls; before Read; at session start, subagent start, when you send a message (to pass on changed rules) and before compaction; and when a turn ends. After kompactor start on macOS and Linux, Claude's Bash commands run through Kompactor's shell prefix (~/.kompactor/bin/kompactor-shell) so failing runs can be compacted too. The prefix runs after Claude Code's permission check, on Claude's original command, and returns its exit code unchanged.

What it adds to Claude's context. Compacted tool output, outlines in place of large file reads, a code map once per session, a one-line savings note after each turn, and short reply rules at session start and for subagents, given again with your next message when you change them. The rules are plain text you can read in kompactor/rules.py.

What it reads. The tool output Claude Code passes to its hooks, the files Claude reads (to outline them), your project's source (for the code graph), and the context size Claude Code gives the status line. Hooks never read your session transcripts. kompactor estimate and the dashboard's Replay your history panel read your local Claude Code session logs in ~/.claude/projects only when you run them; the result isn't stored or sent anywhere.

What it writes. ~/.kompactor/: settings, the savings ledger, raw copies of shortened output (for kompactor show), the code graph index and the ~/.kompactor/bin/ launchers. When kompactor isn't on your PATH, it adds one link to that launcher in a writable folder that already is (~/.local/bin, ~/bin, /opt/homebrew/bin or /usr/local/bin); it never edits shell files or replaces an existing command, and kompactor uninstall removes the link. History is deleted after 30 days by default. kompactor start edits ~/.claude/settings.json to add Kompactor's hooks (non-plugin installs), a status line (only if you have none), CLAUDE_CODE_SHELL_PREFIX (only if it isn't set) and the level's autoCompactWindow (only if you haven't set one; kompactor stop removes it), keeping a backup in settings.json.kompactor-backup; non-plugin installs also get the /kompactor skill in ~/.claude/skills. When VS Code or Cursor is installed, kompactor start adds the Kompactor extension to them with their own code / cursor command (from a copy inside the package; nothing is downloaded), and kompactor uninstall removes it and deletes ~/.kompactor. Nothing is written to your repositories.

What it never does. Change your permission rules or sandbox settings, change what a command does, or send your code or output anywhere. Details: privacy policy.

Troubleshooting

Turn it off or remove it:

kompactor stop        # pause: output passes through untouched; settings are kept
kompactor start       # turn it back on
kompactor uninstall   # remove hooks, status line, shell prefix, skill and editor extension, and delete ~/.kompactor

Then remove the package the way you installed it: claude plugin uninstall amarkum@kompactor, pipx uninstall kompactor, or uninstall the extension in VS Code.

FAQ

Does Kompactor change Claude's answers? In the measured runs, no: 27 of 27 answers were correct with and without it. It removes noise and always keeps errors, failures and summary lines.

Does it send my code anywhere? No. Everything runs locally through Claude Code's hooks.

Why is the per-session saving smaller than the per-command saving? Most of what each turn re-sends is Claude Code's own fixed context: the system prompt, tool definitions and your messages. Kompactor shrinks the tool-output part, which can drop 80–99% per command.

Does it work in VS Code, Cursor or other editors? It works wherever Claude Code runs: the CLI and the Claude Code extension in VS Code and Cursor. It doesn't apply to the Claude chat apps, which don't run plugin hooks.

Can I use it with agents other than Claude Code? The hooks are Claude Code-specific, but kompactor run -- <command> and kompactor filter compact any command's output for other agents and scripts.

How much latency does it add? About 50–100 ms per hook, because the filters run in Python.

How are the dollar figures worked out? At the API list price of the model each session ran on, which Claude Code reports to the status line (Opus 5.5: $4 per million input tokens, cache writes $5, cache reads $0.20). Each token kept out of the context is counted once as a prompt-cache write and again at the cache-read price for every later request that would have re-read it: one per tool call and one per new prompt, until the session compacts. Sessions with no model reported use the model in ~/.claude/settings.json, else $3 per million. To use your own price instead, set kompactor.pricePerMillionTokens in VS Code or pass kompactor gain --price. On a Pro or Max plan these are what the same tokens would cost on the API, not money off your bill.

Is it free? Yes. MIT-licensed, no account, no paid tier.

Development

git clone https://github.com/amarkum/kompactor.git && cd kompactor
python -m unittest discover tests     # 80 tests, including the real shell prefix run as Claude Code runs it
node vscode/test/smoke.js             # VS Code extension against a mock API
claude plugin validate .              # check the plugin manifest
./scripts/build-vsix.sh               # › dist/kompactor-<version>.vsix

Releases: python scripts/bump_version.py X.Y.Z, commit and push to main. The workflow runs the tests and publishes to PyPI with trusted publishing.

Contributing

Bug reports, ideas and pull requests are welcome. See CONTRIBUTING.md for how to set up, test and propose changes, and CHANGELOG.md for what's new.

• Questions and bugs: open an issue
• Security problems: report them privately, as described in SECURITY.md
• Privacy: PRIVACY.md

License

MIT © The Kompactor authors. The dashboard uses the IBM Plex fonts under the SIL Open Font License.