README
Pith
Status: stable — not actively adding features. Bug fixes welcome via issues.
Token compression hooks for Claude Code. Install once, works in every session, zero config.
bash <(curl -s https://raw.githubusercontent.com/abhisekjha/pith/main/install.sh)
How it works
Four hooks attach to Claude Code's lifecycle. Every session, every project, automatically.
PostToolUse— compresses file reads, bash output, and grep results before they hit contextUserPromptSubmit— runs/pithcommands, enforces token ceiling if setSessionStart— restores compression mode, injects cache-locked rulesStop— records token usage forstatusandreport
The PostToolUse hook is where most savings happen — file reads alone account for 30–50% of context in a typical coding session.
| Tool output | What happens | Typical saving |
|---|---|---|
| File reads | skeleton only — imports, signatures, types | −88% per read |
| Bash / build | errors + summary, verbose logs discarded | −91% per run |
| Grep results | capped at 25 matches | prevents runaway searches |
| Large payloads | offloaded to ~/.pith/tmp/, pointer left in context | prevents bloat |
Core features
1 — Auto compression (zero config)
Runs automatically. No commands needed. Every file read, bash run, and grep gets compressed on the way back to Claude.
Real session numbers:
Read large-service.ts → 1,800 tokens baseline → 210 tokens compressed (−88%)
npm install output → 940 tokens baseline → 80 tokens compressed (−91%)
2 — Output modes
Control how Claude writes back to you.
/pith → lean: drop filler, short synonyms, fragments OK
/pith ultra → maximum: abbreviate, arrows, tables
/pith precise → tight but full sentences
/pith off → disable output compression
Auto-escalation kicks in as context fills — no manual switching needed:
50% fill → LEAN
70% fill → ULTRA
85% fill → dynamic token ceiling
3 — Token status
/pith status → ASCII flow chart — baseline vs compressed vs output + plain-English savings
/pith report → interactive HTML dashboard (auto-refreshes every 30s)
4 — Smart file focus
Load only the sections of a file relevant to your current question. Saves re-reading large files.
/focus src/services/auth.ts
Returns the 5 most relevant sections with a structure overview. Works on any file type.
5 — Symbol extraction
Pull exact function or class definitions without reading the whole file.
/pith symbol src/auth.ts handleLogin → exact 30–50 lines (~95% vs full file)
/pith symbol --list src/auth.ts → all symbols with line numbers
Install
# One-liner
bash <(curl -s https://raw.githubusercontent.com/abhisekjha/pith/main/install.sh)
# From source
git clone https://github.com/abhisekjha/pith
bash pith/install.sh
Hooks install globally into ~/.claude/hooks/. Active in every session from that point on.
Update:
/pith update → git pull + re-sync hooks, commands, settings
Uninstall:
/pith uninstall
Advanced features
All present and functional. Not the daily workflow, but there when you need them.
| Feature | Command | What it does |
|---|---|---|
| Project wiki | /pith ingest <file> | Extract entities, claims, decisions into wiki/ |
| URL ingestion | /pith ingest --url <url> | Fetch and ingest a web page |
| Wiki query | /pith wiki "question" | Search wiki with citations |
| Wiki synthesis | /pith compile | Re-synthesize all sources into wiki pages |
| Wiki lint | /pith lint | Find contradictions, gaps, missing pages |
| Knowledge graph | /pith-graph | Visual graph of wiki entities in browser |
| jCodeMunch | auto on code files | Structure-aware ingest — skeleton not full source |
| Token ceiling | /budget 150 | Hard token cap, enforced every prompt |
| Structured formats | /pith debug / review / arch / plan / commit | Output templates |
| Tour | /pith tour | 7-step interactive walkthrough |
| Health check | /pith health | Diagnose hook and config issues |
| Evals | python evals/harness.py | Run compression benchmark (needs API key) |
Honest numbers
Estimates against real usage — not against "no system prompt."
Before Pith: Read large-service.ts → 1,800 tokens
After Pith: Read large-service.ts → 210 tokens (−88%)
Before Pith: npm install output → 940 tokens
After Pith: errors + summary → 80 tokens (−91%)