Spend Claude Code's tokens on your code, not on noise

Install

Kompactor is public: on GitHub, on PyPI and as a Claude Code plugin. Pick one way in. All of them end in the same place, and everything can be changed later from the dashboard. Below, your-org/kompactor stands for your team's repo; when you open this guide from the dashboard, it's filled in.

/plugin marketplace add your-org/kompactor
/plugin install amarkum@kompactor
/kompactor start

pipx install kompactor
kompactor start

code --install-extension kompactor-0.8.6.vsix

Windows: run .\kompactor\install.ps1 from a clone, or use the VS Code extension. The CLI and the VS Code extension read the same ~/.claude/settings.json, so one install covers both. A backup of that file is kept as settings.json.kompactor-backup.

kompactor start adds hooks, a status line (if you don't have one) and, on macOS and Linux, Claude Code's CLAUDE_CODE_SHELL_PREFIX setting pointing at ~/.kompactor/bin/kompactor-shell, which is what lets Kompactor compact failing commands. It never replaces a status line or shell prefix you already have. Restart open Claude Code sessions after setup.

Open the dashboard any time with kompactor start (it runs in the background; kompactor stop turns Kompactor off), or Kompactor: Open Dashboard in VS Code. Its Setup page shows these commands with your repo filled in, ready to copy.

Use it across your team

Everyone can install from the public repo or PyPI. To control what your team runs, fork the repo (privately if you like) and point the commands at your fork; each person's own git access is enough.

Offer it in a project

Commit this as .claude/settings.json in any repo your team works in:

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

When a teammate opens the project and accepts Claude Code's prompt to trust the folder, Claude Code adds the marketplace and turns the plugin on. Each person then runs /kompactor start once (plugins can't set the status line or the shell prefix themselves). autoUpdate keeps everyone on your latest release: teammates get a new version when version in .claude-plugin/plugin.json changes, and python scripts/bump_version.py 0.4.1 bumps it everywhere.

Private-repo access

Claude Code uses each person's existing git login and can't prompt for a password. An SSH key that works with GitHub is enough. Without one, run gh auth login and gh auth setup-git, and set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1.

Set the team's level for a repo

Commit a .kompactor.json next to the code. preset is the level, 1 (Max quality) to 5 (Max savings); overrides sets any option by its name in kompactor config.

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

A repo's file beats each person's global level, and each person's own choice for that project still wins. Entries Kompactor doesn't recognise are ignored. The Projects page shows which repos have team settings.

Script it

The plugin commands also work outside the chat, for onboarding scripts:

claude plugin install kompactor --marketplace your-org/kompactor   # Claude Code 2.1.292+
claude plugin marketplace add your-org/kompactor && claude plugin install amarkum@kompactor   # older

Roll out to every machine

For admins: managed settings take the same extraKnownMarketplaces and enabledPlugins keys. They live in /Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/managed-settings.json on Linux and WSL, C:\Program Files\ClaudeCode\managed-settings.json on Windows, or the managed settings in your claude.ai organisation. strictKnownMarketplaces limits people to approved marketplaces.

Plain pip install kompactor

That needs a package index. Public PyPI would make the code public. To keep it private, build the wheel with pip wheel --no-deps . and upload it to a private index your company already runs, such as Artifactory, AWS CodeArtifact, Google Artifact Registry or Gemfury. Teammates who point pip at that index can then run pip install kompactor.

What happens in a session

Kompactor works through Claude Code hooks, so it acts on every tool call without Claude having to remember to use it. Your commands run exactly as typed; only what Claude reads changes.

Configuration: levels

One level sets every option. Move toward quality and Claude sees more raw output; toward savings and it sees less. Every individual setting can still be changed on the dashboard, globally or per project.

Every request re-sends the whole conversation, so in long sessions most of the cost is the conversation being read again. Each level also sets how large the conversation may grow before Claude Code compacts it into a summary (Claude Code's autoCompactWindow). Compacting earlier is where most of the saving comes from: about 10% at Quality, 19% at Balanced, 35% at Savings and 50% at Max savings, on 65 long sessions replayed with kompactor estimate. The cost is that Claude keeps only a summary of the early part of a long session. A window you set with /autocompact always wins, and kompactor stop restores Claude Code's default.

Changing the level

• Dashboard: Configuration. On the Overview, Before and after shows exactly what Claude got from your real command outputs, with removed lines marked.
• VS Code: click the Kompactor item in the status bar, then Choose quality vs tokens level.
• In Claude Code: type /kompactor balanced, /kompactor max savings and so on.
• Terminal: kompactor config preset 4, or kompactor presets to list them.

Using it from chat

Kompactor installs a small /kompactor skill (about 370 tokens, loaded only when used).

Code graph

Kompactor indexes functions, classes, methods, imports and calls for Python, Go, TypeScript, JavaScript and React on this machine. Building it takes well under a second for most repos, and only changed files are re-parsed. It is stored outside your repo, so it never shows up in diffs.

# find code by topic
kompactor graph query "session cookie signing"
# what breaks if this changes, and which tests to run
kompactor graph impact src/flask/sessions.py
# one symbol: where, who uses it, what it uses, its tests
kompactor graph explain Flask.make_response
# overview, dead code, import cycles
kompactor graph report
kompactor graph unused

You rarely need to type these. Claude gets the outline and the "imported by / tests" line automatically when it opens a big file, and the rules mention the commands in one line.

Seeing the savings

"Context smaller" compares the context Claude carries now with what it would carry without Kompactor, counting everything trimmed since the last compaction. If Claude ends up reading a whole file anyway, the claimed saving for that file is taken back.

Projects and languages

Each repo's languages are detected from pyproject.toml or requirements.txt (Python), go.mod (Go), tsconfig.json or package.json (TypeScript) and a react or next dependency (React). The profile decides which stack frames are library noise, which files are generated, and which lock files collapse in diffs.

Give a repo its own level under Projects, for example Max quality for a payments service and Savings for everything else.

Getting the full output

• Every compacted output ends with a note such as [kompactor: 4210›612 tokens; full output: kompactor show 17]. Claude, or you, can run kompactor show 17, or kompactor show 17 --lines 120-180 for a slice.
• kompactor search "TypeError" searches every stashed output.
• To skip compaction for one command, start it with KOMPACTOR_RAW=1.
• For commands you always want raw, add them to Never compact these commands on the dashboard.
• An outline is never a dead end: repeating the same Read returns the whole file.

Proving it on your repo

kompactor prove runs the same tasks through real headless Claude Code sessions with and without Kompactor, and reports tokens, cost, turns and whether each answer was right. Write a few tasks that look like your team's work:

{ "tasks": [ {
    "id": "failing-tests", "repo": "api",
    "prompt": "Run the tests with `pytest -v` and tell me which fail and why.",
    "tools": ["Bash(pytest:*)", "Read", "Grep"],
    "max_turns": 8, "expect": ["test_refund_rounding"] } ] }

kompactor prove --tasks my-tasks.json --repos ~/code --reps 3 --out evidence

Each run is capped at $1 by default (--budget). The report lands in evidence/REPORT.md. Use --preset 1 to 5 to test a level, and --set name=value to test a single setting.

Kompactor's own results, from 54 sessions on Flask, Cobra, SWR, ky and zustand: 16% fewer tokens and 10% lower cost at the default level, with every answer correct in both arms. Failing test runs and code search gained the most. The same sessions at Max savings came in at 12% fewer tokens and 10% lower cost, and at Max quality close to neutral (+3% tokens, −1% cost).

Troubleshooting

Is it working?

Dashboard › Setup › Run self-test runs every installed hook exactly as Claude Code would and shows pass or fail with timings. From a terminal, use kompactor doctor.

Claude can't run kompactor

Installs from VS Code or a clone add a launcher at ~/.kompactor/bin/kompactor, which Claude can always call. Add ~/.kompactor/bin to your PATH if you want to type kompactor yourself.

Turn it off

Dashboard › Setup › Disable, or kompactor install --uninstall. This removes the hooks, the status line and the shell prefix. Your other hooks and your own status line are never touched. To keep everything except the shell prefix, turn off Compact failing commands too on the dashboard or run kompactor install --no-shell-prefix.

Every command fails with kompactor-shell: not found

~/.kompactor was deleted while Kompactor was still set up. Remove the CLAUDE_CODE_SHELL_PREFIX line from ~/.claude/settings.json, or reinstall and run kompactor install --uninstall. If Kompactor itself is broken or removed but the script is still there, commands simply run untouched.

Where is my data?

In ~/.kompactor: settings (config.json), the savings history and stashed outputs (kompactor.db, pruned after 30 days by default) and code graphs (graphs/). Nothing is sent anywhere.

FAQ

Does it change what my commands do?

No. Commands run exactly as written, with your normal permissions: Claude Code checks Claude's command against your rules before Kompactor is involved. Kompactor only changes the text Claude reads afterwards. The one visible difference: for tests, builds, linters and installs, the shell prefix collects the output until the command finishes, so those lines don't stream live in the terminal. Servers, watch modes and every other command stream as usual, and the exit code is always the command's own.

Does it slow Claude Code down?

Each hook takes about 50 to 90 ms, far less than a model turn. The shell prefix adds about 50 ms to test, build and lint commands and nothing measurable to the rest. Code graphs build in under a second for most repos, in the background for big ones.

How is this different from graphify, ponytail or caveman?

Each of those covers one layer. Kompactor covers command output, file reads, code navigation, reply length and code size together, acts automatically through hooks, keeps its own instructions small, and measures the result in real A/B sessions. The README has a feature-by-feature comparison.

Will Claude miss something important?

Errors, failing tests, your own stack frames and summaries are kept at every level, and the full output is always one command away. If in doubt, use a lower level for that project.