sipcode

Sipcode

Sip your tokens. Don't gulp them.

Token optimization for Claude Code, Cursor, Codex, and other AI coding agents.

An independent study of 38 Claude Code sessions found that only 0.6% of tokens were actual code output. The other 99.4% was exploration, re-reads, and repetition. — DEV Community, March 2026

Sipcode targets the other 99.4%.

npx sipcode why

That one command — no install, no signup, no config — reads the .jsonl transcripts Claude Code already writes to your machine and shows you exactly where your tokens went. Re-read files. Idle context. Cache-creation overhead. The whole story.

What Sipcode produces — one of these per session, shareable

_{generated by npx sipcode receipt — auto-copies to your clipboard with a pre-filled tweet}

Why this exists

Anthropic's enterprise benchmark is $13 per developer per active day on Claude Code. For a 5-person team, that's ~$16,250/year in token spend. Anthropic also removed Claude Code from the $20 Pro plan — pushing the entry-level cost out of reach for many indie devs.

The fixes already exist as fragmented point solutions: Caveman (59k★) for output, RTK for CLI filtering, Graphify (47k★) for codebase graphs, Headroom for API compression, ccusage for measurement. Stacking all of them gets to ~85% reduction — but published guides confirm it takes a full day of manual configuration. Most developers never bother.

Sipcode is the unified one-command installer. Caveman is the engine. RTK is the transmission. Sipcode is the car.

Installation — Step by step

Prerequisite: Node.js (one-time)

If you've never used Node before, install it from nodejs.org. Click the green "LTS" button. Run the installer with all default settings. Done — works on Mac, Windows, and Linux.

To check it worked, open your terminal and run:

node --version

If you see something like v20.11.0 or higher, you're good.

Where's the terminal? Mac: Open Spotlight (⌘ + Space), type "Terminal", press Enter. Windows: Press the Windows key, type "Command Prompt" or "PowerShell", press Enter. Linux: You already know.

Install Sipcode (one command)

npm install -g sipcode

That's the whole install. To verify:

sipcode --version

You should see 1.0.0 (or whatever the latest is).

Don't want to install globally?

Use npx for one-off runs — no install, no commitment:

npx sipcode why          # see where your last session burned tokens
npx sipcode benchmark    # see the measured 62.6% savings number

Your first 60 seconds with Sipcode

1. See where your tokens died — sipcode why

npx sipcode why

Real output from the session that built Sipcode itself:

sipcode why · session 84bbf968 · 60h 26m · claude-opus-4-7
project: C--Projects-Sipcode

you burned 225,576,407 tokens. 936,947 were code output.
the other 224,639,460 were exploration, re-reads, and idle context.
output ratio: 0.4% of all tokens

if sipcode had been on, you could have saved ~4,552,675 tokens this session.
  · smart manifest (S001): 3,856,242 tokens
  · read-once cache (S030): 605,924 tokens
  · diff-output (S021):     90,509 tokens

top leaks (this session):
  1. idle context — 334,432,891 tokens (6 files held without re-reference)
  2. cache-creation overhead — 17,528,372 tokens (context written into cache)
  3. duplicate file reads — 605,924 tokens (2 files read more than once)

duplicate reads:
  · src/modules/why/format-terminal.ts (2× — 390,589 tokens wasted)
  · _export/sipcode_transcript.md (4× — 215,335 tokens wasted)

That's your real money. No setup. No login. Sipcode reads what Claude Code already wrote.

2. Set up Sipcode in any project — sipcode init

cd your-project
sipcode init

Three prompts. Done. Sipcode scans your repo with tree-sitter + git, infers conventions, and writes a .sipcode/manifest.md (<2,000 tokens for a 500-file repo) plus a managed block in your CLAUDE.md. Your AI agent stops blindly exploring on every prompt.

3. Generate a shareable receipt — sipcode receipt

sipcode receipt

Writes a standalone HTML and a 1200×630 PNG to .sipcode/receipts/<id>/, copies the PNG to your system clipboard, and gives you a pre-filled tweet intent URL. Built for sharing.

What you get — all 12 commands shipped in v1.0

Command	What it does
sipcode why	Forensic audit of any past Claude Code session — no install required.
sipcode init	Interactive 3-prompt setup. Runs manifest + injects CLAUDE.md.
sipcode manifest	Tree-sitter + git project map. <2k tokens for 500-file repos. Zero LLM calls.
sipcode receipt	HTML + 1200×630 PNG + clipboard + tweet intent. The viral surface.
sipcode rules	Output Compression — three modes (default / strict / verbose) installed in CLAUDE.md.
sipcode hygiene	Read-once rules + PreToolUse hook (50/70/90% context warnings) + smart /compact suggestions.
sipcode estimate "<task>"	Predicts session cost per model (Opus / Sonnet / Haiku) before you run it. Zero LLM calls.
sipcode stats	Cross-session analytics — totals, sparkline, top-N expensive sessions, optional standalone HTML.
sipcode score	24-check static audit of your codebase's "agent-friendliness." Tier badge + Shields.io endpoint + composite GitHub Action.
sipcode benchmark	Reproducible 20-task benchmark suite. 62.6% median savings. Published methodology.
Multi-agent: --agent cursor	sipcode init --agent cursor writes .cursor/rules/sipcode.mdc.
Privacy guarantee	Local-first by engineering. Asserted by a static test that fails CI if a network module is ever imported in a core path.

NEW in v1.1 — Sipcode inside Claude Desktop chat (MCP server)

Run Sipcode tools live inside the Anthropic Claude Desktop app. Ask Claude "audit my last session" and it calls Sipcode in the chat.

🪟 Windows install (verified end-to-end)

# 1. Install Sipcode (one-time)
npm install -g sipcode

# 2. Verify the MCP binary works (you should see "[sipcode-mcp] connected")
sipcode-mcp        # Ctrl+C to exit after the connected line prints

Then in Claude Desktop:

• Click ☰ menu → Settings → Developer → Edit Config
• Paste this exact JSON (or add "sipcode" to your existing mcpServers):

{
  "mcpServers": {
    "sipcode": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "sipcode-mcp"]
    }
  }
}

⚠️ Critical Windows-only detail: the "command": "cmd" with ["/c", ...] wrapper is required. Without it, Claude Desktop registers the server but fails to launch it. macOS/Linux users use "command": "npx" directly — Windows must use cmd /c.

• Fully quit Claude Desktop: system tray (bottom-right) → right-click Claude icon → Quit. Closing the window is not enough — the app keeps running in the tray.
• Reopen Claude Desktop. Open a new chat. Ask:

What MCP tools do you have from sipcode?

You should see Claude list the four tools: list_recent_sessions, audit_latest_session, get_project_manifest, estimate_task_cost.

🍎 macOS / 🐧 Linux install

Same as above, except in step 4 use:

{
  "mcpServers": {
    "sipcode": {
      "command": "npx",
      "args": ["-y", "sipcode-mcp"]
    }
  }
}

The config file lives at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

4 prompts to verify it's working end-to-end

Once you've reopened Claude Desktop, paste these one at a time into a new chat:

Use sipcode to list my 5 most recent Claude Code sessions.

Expected: a table with real session IDs and timestamps.

Run sipcode's audit_latest_session and show me the output ratio, top 3 leaks, and dollar cost.

Expected: a forensic breakdown like 0.3% output ratio, top leaks named by file, real $ amount.

Use sipcode to estimate what refactoring 5 files in C:\Projects\YourProject would cost on Opus 4.7, Sonnet 4.6, and Haiku 4.5.

Expected: three specific dollar predictions per model.

Read my Sipcode manifest at C:\Projects\YourProject and tell me the architecture.

Expected: Claude summarizes the architecture without grepping any source files.

If all four return real data — Sipcode is live in your Claude Desktop. Full setup guide and troubleshooting: docs/MCP.md.

What Sipcode does — and doesn't do — to your Claude

Trust matters. Here's what changes (and what doesn't) when you install Sipcode.

Command	Effect on your Claude sessions
sipcode why, stats, receipt, score, estimate, benchmark	🟢 Zero effect. Read-only on your local transcripts. Claude Code behaves identically with or without these.
sipcode manifest (no --inject)	🟢 Zero effect. Writes only to .sipcode/manifest.md — Claude Code doesn't auto-read this.
sipcode init, rules --install, hygiene --install	🟡 Explicit, transparent modifications. Adds clearly-marked sipcode blocks to your CLAUDE.md and (for hygiene) hooks to ~/.claude/settings.json. Fully reversible with --uninstall.
sipcode-mcp (Claude Desktop MCP server)	🟡 Dormant unless invoked. Doesn't intercept or modify anything Claude says. Only runs when Claude calls one of its 4 tools — which only happens when you ask a question Claude thinks the tool can help with.
Anything else	Doesn't exist. There's no background daemon, no telemetry, no auto-updater, no network call.

Bottom line: read-only commands change nothing about Claude. Modification commands always require an explicit --install flag and are 100% reversible. Privacy guard test (tests/privacy/no-network.test.ts) asserts there are zero node:http/https/net/dns imports in any core path — fails CI if anyone ever tries to add one.

(Original quick MCP overview — kept for reference)

// add to claude_desktop_config.json
{
  "mcpServers": {
    "sipcode": {
      "command": "npx",
      "args": ["-y", "sipcode-mcp"]
    }
  }
}

Restart Claude desktop. Now in any chat, you can ask:

"How expensive would it be to refactor my auth pipeline?" (Claude calls Sipcode's estimate_task_cost tool → returns a real cost band)

"Where did my tokens go in yesterday's session?" (Claude calls audit_latest_session → returns the same forensic report sipcode why gives)

"Read my project manifest before exploring." (Claude calls get_project_manifest → gets the <2k-token map instead of grepping)

Sipcode is the first token-optimization tool that lives inside the Anthropic chat experience itself. Works in Claude desktop, Claude Code, Cursor, Continue, and any MCP-aware client. Full setup + tool reference: docs/MCP.md.

The killer numbers (all sourced)

Number	Meaning	Source
0.6%	Of all tokens in a typical Claude Code session, only this fraction is code output. The rest is waste.	dev.to study of 38 sessions
62.6%	Median measured token reduction across Sipcode's locked 20-task corpus. Range: 37.4% – 80.6%.	npx sipcode benchmark — run it yourself
5.5×	How many more tokens Cursor burns than Claude Code on identical tasks.	Sitepoint benchmark 2026
$13/day	Anthropic's own enterprise benchmark for Claude Code spend.	Anthropic Claude Code Costs docs
77%	Of context that is repetitive across turns in a typical session.	Prior session research
$30,000/yr	What a 10-person team saves with Sipcode active. Reclaimed simply by npm install.	$13 × 10 × 365 × 0.626

How much does this actually save you?

At the measured 62.6% median:

Your setup	Daily spend (before)	Daily spend (after)	Annual savings
Solo dev, ~$5/day on Opus	$5.00	$1.87	$1,143/yr
5-person team, $13/dev/day baseline	$65.00	$24.30	~$15,000/yr
10-person team	$130.00	$48.60	~$30,000/yr

The 0.6% study finding in practical terms: of every $100 you spend on Claude Code, only 60¢ is actual code output. Sipcode targets the other $99.40.

The $20/month Claude Pro plan that Anthropic removed Claude Code from is now effectively a $5–7/month plan in token economy terms.

How Sipcode is different from everyone else

Tool	What it solves	What it misses
Caveman (59k★)	Output compression via prompting. Saves ~20% of total spend (output is 20–30% of bill).	Input tokens, file reads, measurement, idle context.
Graphify (47k★)	Knowledge graph from code via LLM extraction. Helps navigation.	Costs tokens to BUILD the graph. Stale on every code change.
RTK	CLI output filtering (git, ls, npm) before it hits context.	Doesn't touch file reads or output. Single-layer fix.
context-mode	Sandboxes large tool outputs in separate processes.	Doesn't manage manifest, doesn't measure, doesn't compress output.
ccusage	Measures total token spend cleanly.	Just measures. Doesn't show where the spend went or how to fix it.
Sipcode	Where it went, why it cost that much, how to save next time — twelve features, one install, one offline CLI.	—

Plus four things no other tool has:

• sipcode estimate "<task>" — predicts session cost per model BEFORE you run. Nobody else does this for agent sessions.
• sipcode score — audits any codebase for "agent-friendliness." 24 checks across 5 categories. Shields.io badge included. Competing tools audit your agent config; Sipcode audits the codebase the agent has to navigate.
• Reproducible benchmark — Sipcode publishes its own methodology and corpus. Every savings number is git clone && npx sipcode benchmark away from verification.
• Engineered privacy — local-first, asserted by tests/privacy/no-network.test.ts which fails CI if any core path imports a network module. Not a promise — a test.

See the measurement in action

sipcode stats — your spend, audited

sipcode stats · last 30 days · 580 sessions · claude-sonnet-4-6

across 580 sessions you burned 2,876,528,359 tokens.
output ratio: 0.9% of all tokens — 99.1% was exploration, re-reads, and idle context.

estimated wasted on patterns sipcode catches:
  · duplicate file reads            23,859,519 tokens   ($7.16)
  · idle context                26,115,911,079 tokens   ($7,834.77)
  · cache-creation overhead        218,029,191 tokens   ($245.28)

trend: token spend per day (30 days)
  ▁▁▁▁▂▁▁▁▁▁▁▁▁▁█▁▁▁▁▁▁▄▁▁▁▁▁▂▁▁
  min: 0  ·  max: 1.3B  ·  median: 7.2M

Pass --html to get an interactive standalone report. Pass --here to scope to the current project only.

sipcode benchmark — the published numbers, reproducible

sipcode benchmark · 20 tasks · corpus v1.0.0

62.6% median savings · range 37.4% – 80.6%

total saved: 3,567,170 tokens · $67.43

per-task results
id     savings  bar                       baseline   optimized  saved
BT001   62.5%  ███████████████░░░░░░░░░     563,300    211,380     $7.13
BT002   64.1%  ███████████████░░░░░░░░░     165,300     59,410     $1.99
BT003   77.2%  ███████████████████░░░░░     278,900     63,720     $3.15
BT008   80.6%  ███████████████████░░░░░     218,500     42,280     $2.67
BT011   78.1%  ███████████████████░░░░░     247,500     54,250     $3.15
...
where the savings came from
  S001 smart manifest:           471,829 tokens (31.8%)
  S021 output compression:       556,618 tokens (37.5%)
  S030 read-once cache:          455,543 tokens (30.7%)

The full methodology — what we measure, what we don't, how to reproduce, how to challenge a number — lives in benchmark/METHODOLOGY.md. Including the Hardest Tasks subset (sipcode benchmark --hardest), the canonical waste-maximizing corpus designed for cross-tool comparison.

Privacy

Sipcode is local-first, zero-telemetry by default. Nothing leaves your machine.

• No analytics, no signup, no account, no signed-in mode.
• The receipt PNG and HTML are generated locally and stay on disk until you share them yourself.
• The architecture has no network calls in the core paths (why, manifest, receipt, rules, estimate, stats, score, benchmark, hygiene).

This is not a promise — it's an asserted property. A static test (tests/privacy/no-network.test.ts) scans every TypeScript source file in src/ and fails CI if a network module is ever imported in a core path. If that test fails on a release tag, that release violates this claim. Open an issue immediately.

When (if) hosted analytics ship in a future version, they'll be explicit opt-in via a separate command, the source code that handles network IO will be quarantined to src/modules/cloud/ clearly excluded from this guarantee, and you'll get a clear notification on first install.

Full audit: PRIVACY.md.

Get the badge

After running sipcode score --badge once, you'll have a .sipcode/badge.json file. Commit it and add this to your repo's README:

![sipcode score](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/<you>/<repo>/main/.sipcode/badge.json)

Or use the composite GitHub Action (action/action.yml) to auto-generate and publish the badge on every push:

- uses: Anuj7411/sipcode@v1
  with:
    threshold: 70

What's coming in v2.0

The v1.0 wedge is complete. v2 is about depth, distribution, and ecosystem:

Feature	What it does	Status
Multi-agent expansion — Codex / Gemini CLI / Aider / OpenCode	Same wedge, every agent. Each one ships its own transcript parser + agent-specific config injection.	🛠️ in design
sipcode plan "<task>" — Spec-first mode	Instead of the agent exploring the repo (expensive), Sipcode runs a cheap planning pass that produces a structured spec. The agent then works against the spec + relevant manifest slices, not the full repo.	🛠️ in design
sipcode link — Team mode + hosted analytics	Optional, explicit opt-in. Anonymized cross-session metrics across your team. Org dashboard showing aggregate savings. Free tier for individuals, paid tier for teams.	🛠️ planned
Web UI — sipcode.dev	A no-CLI-required dashboard for non-technical users who want the receipt + stats experience without a terminal.	🛠️ planned
VS Code + Cursor extension	Real-time token cost in the status bar. See your session-running cost like a meter.	🛠️ planned
The Sipcode Index — quarterly published report	Industry-standard cost benchmark across all coding agents — Claude Code, Cursor, Codex, Gemini CLI, Aider — measured against the same Hardest Tasks corpus. Becomes the cited source.	🛠️ planned
Cookbook of optimization recipes — community PRs	Open-source, community-edited library of patterns. "Use grep instead of read for code search" — each pattern with measured savings. Hacktoberfest-friendly.	🛠️ open after v1.0 launch
Predictive pre-summarize — warm cache	When the agent edits auth.ts, Sipcode pre-generates compressed summaries of files commonly co-edited with it (from git history). Read-Once Cache, but predictive.	🛠️ research
sipcode doctor — diagnose a slow setup	Static analyzer that scans your CLAUDE.md + .sipcode/ for misconfigurations, stale entries, missing rules.	🛠️ planned
Fair Plan Calculator	Given your usage, recommends the cheapest Anthropic plan that covers you. Sometimes recommends DOWNGRADING.	🛠️ planned

Architectural principles (the engineering Sipcode runs on)

For curious developers — eight non-negotiable rules:

• Pure runners + I/O wrappers. Every analyzer is a pure function over an in-memory model. I/O lives in thin wrappers (FileSystem, Clock, ProcessEnv, Git, Clipboard seams).
• Branded types with real validators. SessionId, AbsoluteFilePath, TokenCount aren't just strings — they're constructors that throw on bad input.
• Result<T, E> in pure runners. Never throws mid-flight. Throws live only at I/O boundaries.
• Stable check IDs as public API. S001, M001, R001, E001 — once shipped, renames are breaking changes.
• Drift-prevention snapshot tests. Every generated artifact (manifest, HTML report, PNG receipt, JSON output, CLAUDE.md injection) is snapshot-tested.
• Locale-stable number formatting. Pinned to en-US so receipts look identical on every machine.
• Zero LLM calls in static analysis paths. Static-only. This is the line that separates Sipcode from Graphify.
• DX-cost accounting. Every optimization carries a dx_cost rating alongside est_savings. We never trade silent quality loss for token savings.

Test coverage: 787 tests passing. ≥85% coverage on every shipped module. tsc --noEmit clean. No any, no @ts-ignore.

Contributing

Sipcode is MIT, free forever, solo-dev-maintained — but PRs welcome.

The fastest way to contribute is to add a recipe to the optimization cookbook (opening after v1.0 launch). If you've found a pattern that saves tokens in your own sessions, it can ship as a tested recipe with a measured savings number.

Bug reports, feature requests, and weird edge cases → open an issue.

Built by

Anuj Ojha — solo dev. Also author of Answerable, the SEO optimization CLI for Next.js.

Sipcode exists because I burn through my Claude Code Max allocation in two hours. If you do too, this is for you.

License

MIT — free, forever, no premium tier, no telemetry, no signup.

If Sipcode saves you a dollar, leave a ⭐ on the repo.

If it saves you a hundred, open an issue with what it caught — we publish corpus improvements quarterly.

Sip well.