Metadata-Version: 2.4
Name: compact-code
Version: 0.1.0
Summary: Dense Python for AI agents, readable view for humans. Same logic, ~30-55% fewer tokens.
Author-email: Emmanuel Freund <freund.emmanuel@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ast,claude,llm,minify,tokens
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.9
Provides-Extra: exact
Requires-Dist: tiktoken>=0.5; extra == 'exact'
Description-Content-Type: text/markdown

# 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 codebase read |

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

## 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
