compact-code 0.2.0

Dense Python for AI agents, readable view for humans. Same logic, ~30-55% fewer tokens.

compact-code

Dense Python for AI agents, readable view for humans. Same logic, fewer tokens.

AI coding agents (Claude Code, Cursor, Codex...) read your code far more often than they write it. Every Read, every context refill re-pays the token weight of your code. But your code is written for humans: comments, docstrings, type annotations, blank lines, 4-space indentation — none of which the agent needs to understand the logic.

compact-code removes all of it, provably without changing the program (the AST is preserved), and gives you back a readable view on demand. Think minified JS + source maps, applied to the AI workflow.

pip install compact-code
cd your-project
compact-code compact        # 3 seconds, AST-safe, reversible via git
pytest                      # your tests are the safety net
compact-code stats          # see what you now save on every read

What it does

• removes comments, docstrings and type annotations (keeps functional class-field annotations: dataclasses, NamedTuple, pydantic)
• strips blank lines, re-indents to 1 space
• never touches string contents, public names, parameters or logic
• verifies AST equivalence on every file before writing — if the check fails, the file is skipped

Measured results

Benchmarked with twin-codebase experiments (identical prompts, blind agents, real test suites as judges — full methodology in the repo):

Scenario	Session-token savings
Surgical one-file fix	~0% (agent barely reads code)
Maintenance on a fully compacted codebase	-31%
Codebase exploration / audit (replicated n=3)	-56%

Quality: across 16 paired sessions, agents on compacted code passed exactly the same test suites and evals as agents on normal code. Zero measured loss.

Codebase density gain: -19% to -41% tokens depending on the project (less if docstrings must be kept).

Commands

Command	What it does
compact-code compact [paths]	compact **/*.py in place (skips .venv, .git, etc.)
compact-code compact --check	dry run: report savings without writing
compact-code compact --keep-docstrings	keep docstrings (use when they are functional: CLI help text, doctests, flit)
compact-code expand <file>	print a readable 4-space-indented view (--write to rewrite in place)
compact-code stats	tokens and $ saved: per full read + cumulative real agent reads
compact-code install-hook	install a Claude Code hook that counts real savings on every agent read (--project for project-level)

Install compact-code[exact] for exact token counts (tiktoken).

The live savings counter

compact-code install-hook    # one-time, hooks into Claude Code
# ... let your agent work ...
compact-code stats
# Agent savings so far: 142 reads of compacted files, 87,310 tokens saved (~$0.26).

The hook fires on every Read Claude Code performs; if the file is in this project's compaction manifest, the per-file saving (prorated for partial reads) is credited to a local ledger. No network, no telemetry — everything stays in .compact-code.json.

The honest fine print

• The gain is proportional to how much code your agent actually reads. Exploration-heavy and read-heavy sessions save the most; one-file quick fixes save nothing.
• Some docstrings are functional (click help text, doctests, flit metadata). Always run your test suite after compacting; on failure, restore via git and re-run with --keep-docstrings.
• Token counts use tiktoken o200k_base as a proxy for your model's tokenizer; ratios are indicative.

License

MIT