Install in 30 seconds
npm i -g sipcode
sipcode init
That is it. Your next Claude Code session will use Sipcode automatically. Verify a few minutes later:
sipcode drift
If the output reads no drift, context health stable, Sipcode is doing its job.
Already installed? Keep it fresh. Sipcode makes zero network calls, so it can't pop an "update available" notice. Build a weekly habit: run sipcode update (or npm i -g sipcode@latest) to pull the latest fixes. Full details in Updating Sipcode.
What is Sipcode?
Sipcode is a free command-line tool that sits between you and Claude Code. It does three things:
- It watches Claude Code's context window and warns you when it starts to bloat (we call this "context rot")
- It catches duplicate file reads and other waste before they reach Claude, so you pay less for the same answers
- It gives you receipts. Every saving is measurable in your terminal.
It is open source under the MIT license. It makes zero network calls during normal use. Your data never leaves your laptop.
How Sipcode compares
| Sipcode | Tool A | Tool B | Tool C |
|---|
| Approach | Live PreToolUse hook | Cross-session memory store | Static methodology | RAG retrieval server |
| Caps verbose tool output | ✓ | ✗ | docs only | ✗ |
| Dedups same-session re-reads | ✓ | ✗ | docs only | ✗ |
| Mid-session install support | ✓ Verified Warm-Fill | n/a | n/a | n/a |
| Zero false-dedup by construction | ✓ | n/a | n/a | n/a |
| Reproducible benchmark on locked corpus | ✓ 62.6% median (20 synthetic tasks) | ✗ | ✗ | ✗ |
| Self-introspection MCP tools | ✓ 16 tools | ✗ | ✗ | partial |
| Agents covered | Claude Code (all features); OpenAI Codex (spend analytics and usage limits, no hook) | not compared | not compared | not compared |
| Zero network calls in normal use | ✓ | ✓ | n/a | ✗ |
| MIT licensed | ✓ | ✓ | ✓ | ✓ |
Sipcode is complementary to memory tools that persist context across sessions (Tool A in the table). Sipcode keeps each individual session clean. They solve different problems. Run both for maximum effect.
Full feature-by-feature comparison with tool names revealed: anuj7411.github.io/sipcode/compare
Why you probably want it
If you use Claude Code for real work, you have already felt this:
- Long sessions get expensive fast. A two-hour session on Claude Max can burn through your daily plan
- Quality drops as the context window fills. Claude starts re-reading files, repeating itself, losing the thread of what you asked
- You cannot tell what is bloat and what is signal
Sipcode measures the bloat, then removes the parts Claude does not need. Run sipcode benchmark on any machine and you will see the same 62.6% median reduction on the locked 20-task corpus. That corpus is synthetic: scripted pairs of Claude Code transcripts (without and with Sipcode), not recordings of live sessions. It shows what Sipcode's mechanisms remove from a modeled session. Your own number depends on your workload, and sipcode impact measures it on your real sessions.
The two-minute tour
After installing, here are the five commands that show you what Sipcode is doing.
1. sipcode drift
Tells you if your current Claude Code session is drifting from your normal usage pattern. Bloated context, repeated reads, stale signals are all flagged here.
✓ Sipcode drift: no drift, context health stable vs your recent baseline.
By default it checks your most recent session, across Claude Code and Codex. --session <id> checks a specific one, --here limits it to sessions from the folder you are in, and --agent claude-code or --agent codex picks the tool.
2. sipcode proxy --stats
Shows what Sipcode caught in the current session, broken down by rewriter.
Sipcode proxy, rewrite stats
total rewrites: 144
est. tokens saved: ~288,685 (heuristic)
signal kept: 67% (med), weighted across all rewrites
3. sipcode benchmark
Runs the locked 20-task corpus and produces a reproducible savings number. Anyone, anywhere can run this and get 62.6%. The transcripts are scripted, not recorded from live sessions, so read it as a model of Sipcode's mechanisms rather than a measured bill (see METHODOLOGY).
62.6% median savings on a locked 20-task corpus
range 37.4% to 80.6% 3,567,170 tokens $22.48
4. sipcode today
Daily spend summary. Tokens used, sessions, output ratio, comparison to your 30-day median.
spend so far $1.20 across 4 sessions
tokens so far 943.8K output ratio 3.7%
5. sipcode forecast
Month-end projection based on your last 14 days.
projected month-end $17,674 (range $14,139 to $21,208)
Codex
Sipcode also reads OpenAI Codex CLI session logs (~/.codex/sessions and ~/.codex/archived_sessions, or the folder CODEX_HOME points to). For Codex this is spend analytics and usage limits: Sipcode reports what your Codex sessions used, where the tokens went, and how close you are to your plan's limits. It does not change what Codex does.
Commands that read Codex: stats, today, forecast, trend, impact, why, receipt, drift, regress and limits (Codex only), plus the session tools in the MCP server (they take an optional agent input: "claude-code" or "codex") and get_codex_limits.
-
--agent codex shows Codex only. --agent claude-code shows Claude Code only.
-
With no --agent flag and both tools installed, stats, today, forecast, trend and impact print one section per tool. stats, today and forecast end with one combined line, in this shape:
Both tools: <total tokens> tokens · ~$<Claude Code> + ~$<Codex>
-
why, receipt and drift report on the most recent session across both tools. When the other tool has a recent session too, a one-line hint names it and the flag that shows it.
-
--here works for Codex too: it matches the working folder Codex recorded for each session.
-
--json covers one tool per call. Without --agent it covers Claude Code and prints a note on stderr when Codex logs exist too. Add --agent codex for Codex JSON.
-
With no --agent flag on a machine with Cursor and Codex, Sipcode shows Codex (it does not read Cursor's session logs).
How Codex tokens are counted. Sipcode reads Codex's per-request usage records, or, in logs from older Codex versions, the change in the running total Codex logs after each request. Cached input is part of Codex's input count, so Sipcode never bills cached tokens twice. A request copied into a resumed or forked session file is counted once. On the maintainer's machine, Sipcode's per-file totals equal Codex's own final total_token_usage on all 15 real session logs, and an independent counter that shares no code with Sipcode (scripts/verify-counts.mjs) cross-checks every period command against the same logs.
Prices. Codex models are priced from OpenAI's API price table (developers.openai.com/api/docs/pricing, and each Codex model's page under developers.openai.com/api/docs/models, as of 2026-10-09), including the long-context rate for prompts over 272,000 input tokens. A model with no known price is shown as unpriced: its tokens are still counted, a line under the cost says how many were left out of it, and it is never shown as $0.
Not supported for Codex yet: writing rules to AGENTS.md (rules, and the rules step of init), registering the MCP server in Codex, the proxy and hooks (proxy, hygiene), estimate and benchmark. rules --agent codex and estimate --agent codex stop with error E009 instead of showing Claude Code data.
Compressed Codex logs. Codex compresses older session logs to .jsonl.zst. Sipcode reads them exactly like plain logs on Node.js 22.15 or newer. On an older Node.js it skips them, and every report starts with a warning that says how many it could not read and that reading them needs Node.js 22.15 or newer. A damaged or unreadable log gets the same kind of warning. With --json the warning is a note on stderr and the JSON is unchanged.
Codex limits: sipcode limits
Codex writes your plan's usage-limit readings into its own logs after each request. sipcode limits reads them, with zero network calls, and answers three questions: when will I hit my limit, what used it, and did it shrink.
Example output of sipcode limits --since all (the tokens-per-1% history here goes back further than the default 90 days):
sipcode limits · Codex · plan: go · as of 2h ago (your last Codex request)
Weekly limit 62% used resets Wed 14 Oct 14:00 at this pace: runs out Tue 13 Oct ~18:00
30-day limit 22% used resets Mon 2 Nov at this pace: lasts until reset
What used your weekly limit (since Wed 7 Oct)
0199a1b2-c3d4-7a11 sipcode 31% 3.1M tokens
0199a0f7-11aa-7b02 my-app 17% 1.4M tokens
codex-auto-review (9 requests) 6%
unattributed (no Codex requests on this computer) 8%
Tokens per 1% of your weekly limit (gpt-5.4)
Mar 28: 425K Apr 1: 357K Apr 13: 77K
Possible limit cut around Apr 13: 5.1x fewer tokens per 1%.
Limits cover your whole account. Codex use on other devices or in the cloud
is not in these logs and can look like a cut.
- Every limit window the logs report (5-hour, weekly, 30-day): percent used, reset time, and when it runs out at this pace. The pace is the percent used divided by the time since the period started, counted up to now, so the estimate moves later while you are not using Codex. "as of" is your last Codex request: the percent is only as fresh as that.
- What used it: the current period's top 5 sessions and projects (folder name only), plus Codex's automatic reviews as one line. Each rise in the percent is shared by the requests made since the previous rise, in proportion to their tokens. A rise with no request on this computer shows as
unattributed, because limits are shared with your other devices and Codex cloud.
- Did it shrink: how many tokens 1% of the limit bought in each finished period with at least 20% used, compared only within one model (a period counts when 90% or more of its tokens came from one model). Periods that started on the same day also show their start time (
Jul 5 16:39). Possible limit cut appears when a period bought at most half the median of at least two earlier periods. It always says "possible": Codex use on another device raises the percent without local tokens.
- Options:
--json; --since <window> (default 90d), how far back the tokens-per-1% history goes; --here narrows only the "what used it" list to sessions from the current folder (limits are account-wide).
sipcode today adds one line for the Codex limit closest to running out, when Codex has logged limit readings. today --json is unchanged.- MCP:
get_codex_limits (optional since) returns the same JSON as sipcode limits --json.
- Claude Code's logs do not record limits, so
limits --agent claude-code stops with error E009.
Did it get worse after an update? sipcode regress
sipcode regress checks your own Claude Code and Codex logs for regressions that arrive with an update, and names the version that brought each one. Each version is compared with your other versions, so no outside baseline is needed, and nothing leaves your machine.
Example output (one machine's logs; your numbers will differ):
sipcode regress · local only, no network
Claude Code: 27,671 interactive requests in 42 sessions (710 subagent and Agent SDK requests left out of the comparison), 2026-05-04 to 2026-10-12, versions 2.1.121 to 2.1.295
Known-regression windows your logs cover: R1, R4, R5
Codex: 930 requests in 15 sessions, 2026-03-28 to 2026-10-08, versions 0.118.0 to 0.162.0, 3 version/model groups with enough limit data
No regressions detected in your logs.
| Check | What it looks for | Confirmed regression it catches |
|---|
warm-cache-miss | back-to-back requests (under 5 minutes apart) that re-write most of the context | R2: --resume prompt-cache miss (2.1.69 to 2.1.89) |
post-idle-cold | the cache staying cold for the next requests after a break of an hour or more | R3: thinking history cleared after an idle hour (2.1.85 to 2.1.100) |
ttl-5m | main-conversation cache written with the 5-minute TTL instead of 1 hour | R4: 1-hour cache TTL downgraded to 5 minutes (fixed in 2.1.129) |
uncached-input | large uncached input on requests right after a tool result | R1: Fable 5.1 tool context re-sent uncached (2.1.257 to 2.1.259) |
hourly-rebuild | the whole prompt cache rebuilt about every hour | R5: OAuth refresh rebuilt the cache hourly (fixed in 2.1.248) |
codex-limit-burn | a Codex version using more of your limit per token than your other versions on the same plan and window | none in the catalog |
- A finding outside the known catalog is a signal worth reporting, not proof of a bug. A Codex finding could also be a limit change on your plan at the same time, and Codex on your other devices or in the cloud shares the same limit.
- Subagent and Agent SDK requests are left out: their cache policy differs by design.
--bug-report adds a block to paste into a GitHub issue: token counts, versions, dates and short session ids only. Review it before posting.--json for scripts, --agent claude-code or --agent codex for one tool, --min-n <n> for the minimum requests per version a check needs (default 20).- If no logs can be read (for example a sandbox blocks the folders), it prints "Nothing to analyse ... This is NOT a clean result." and exits with code 2. With too little data it says "Not enough data to compare versions yet". When one tool was compared and the other was read but had too little data, it names that tool ("Not enough data to compare Codex versions yet"), so a missing finding for it is not a clean result.
- An independent counter that shares no code with Sipcode (
scripts/verify-counts.mjs) recomputes the coverage, every check's table and the findings of regress --json from the same logs.
Use Sipcode inside Codex
The Sipcode plugin lets you ask Codex about your own usage in plain words, in the ChatGPT desktop app or in the Codex CLI. Each answer comes from the sipcode command on your computer, reading your local logs.
Step 1. Install Sipcode once (Node.js 20 or newer), in a terminal:
npm i -g sipcode
The plugin runs this installed sipcode. It does not use npx, because Codex's sandbox usually blocks downloads.
Step 2. Add the plugin. Follow the path that matches how you use Codex.
If you use Codex only in the ChatGPT desktop app (typing codex in a terminal says it is not recognized):
-
Open a terminal (PowerShell on Windows, Terminal on macOS) and run these two commands:
npx -y @openai/codex plugin marketplace add Anuj7411/sipcode
npx -y @openai/codex plugin add sipcode@sipcode
npx runs OpenAI's Codex CLI (npm package @openai/codex) without installing it; the first run downloads it, which can take a minute. The first command adds this repository as a plugin marketplace named sipcode, the second installs the Sipcode plugin from it. Both write to ~/.codex, the folder the desktop app reads its plugins from.
-
Quit the ChatGPT desktop app completely and open it again.
-
Open Plugins and check that Sipcode is there (pick the sipcode marketplace as the source if the list does not show it). If it is not marked as installed, install it from there.
-
Start a new chat.
OpenAI's docs do not describe a button in the desktop app for adding a marketplace from GitHub on a personal account, which is why this path uses the CLI command once. You do not need to keep the CLI installed.
If you have the Codex CLI (codex --version works):
- Run
codex plugin marketplace add Anuj7411/sipcode.
- Run
codex plugin add sipcode@sipcode, or open /plugins in Codex, choose the sipcode marketplace and install Sipcode.
- Start a new Codex session. If you also use the desktop app, quit and reopen it.
Step 3. Ask:
| Ask | Sipcode runs |
|---|
| "How much did I spend on Codex this month?" | sipcode forecast --agent codex --json (also today and stats) |
| "How close am I to my Codex limit? Did it shrink?" | sipcode limits (its terminal output, for local times) |
| "Why was my last Codex session so expensive?" | sipcode why --agent codex --json |
| "Did Codex or Claude Code get worse after an update?" | sipcode regress --bug-report |
- If Codex's sandbox blocks
~/.codex or ~/.claude, the plugin asks for permission to run the command with read access instead of reporting an empty result.
- Dollar figures are at API prices; on a ChatGPT plan you are not billed per token.
- Answers show numbers the way the
sipcode terminal output does: dollars to the cent, whole percents, and times in your local time zone, never raw JSON values.
- The plugin is instructions only (four skills): no hooks, no MCP server, no network calls.
- Ask in a new, short chat. Codex re-sends the whole conversation with every request, so the same question asked at the end of a long work chat uses far more of your limit than in a fresh one. Each answer runs one Sipcode command, with no extra checks first.
- To update the plugin later, run
npx -y @openai/codex plugin marketplace upgrade sipcode (or codex plugin marketplace upgrade sipcode), then restart the desktop app and start a new chat (a chat keeps the skill instructions it started with). Update the sipcode command itself with npm i -g sipcode@latest.
How to install (more detail)
Sipcode works on Mac, Linux, and Windows. You need Node.js 20 or newer, and Node.js 22.15 or newer to read the session logs Codex compresses (.jsonl.zst).
Step 1. Install Node.js
Skip this step if you already have Node.js. Otherwise:
- Mac:
brew install node
- Linux: open nodejs.org/en/download, choose the LTS version, Linux and nvm, and run the commands shown there. (The
nodejs package in Ubuntu's and Debian's own repositories is often older than Node 20.)
- Windows: Download from nodejs.org
Verify it worked:
node --version
You should see v20.0.0 or higher.
Step 2. Install Sipcode globally
npm i -g sipcode
This downloads Sipcode from npm and makes the sipcode command available everywhere.
If you see permission errors on Mac or Linux, try:
sudo npm i -g sipcode
Verify it installed:
sipcode --version
You should see 1.7.2 or higher.
Step 3. Run sipcode init to wire it into Claude Code
sipcode init
This command does four things:
- Creates a small
.sipcode/manifest.md file in your current project so Claude knows what your project is about
- Adds a small block to your
CLAUDE.md (or creates one) with rules that keep Claude's replies terse
- Installs the Sipcode hook into Claude Code, which is the thing that actually saves tokens
- Marks the date so
sipcode impact can show you before-and-after savings later
You will see a checklist as it runs. Each step shows a checkmark when it completes.
The two questions it asks (and what to pick):
1. Manifest budget. How lean to keep the project summary Sipcode injects.
- tighten (recommended): auto-trims low-signal sections so the summary stays lean, and never blocks you.
- strict: hard-caps the manifest at 2k tokens and refuses if it would go over.
- off: no cap, the manifest can grow to any size.
2. Output compression rules. How terse Claude's replies are in this project.
- default (recommended): diff-style edits, no "here's what I did" preamble.
- strict: telegraphic, clipped replies, for power users who want maximum brevity.
- verbose: extra context and explanation, good while you are still learning the tool.
- skip: don't install reply rules at all.
Not sure? Take the recommended option in each. You can change either choice later: run sipcode rules --mode <default|strict|verbose> for the reply style, or re-run sipcode manifest to regenerate the summary.
Step 4. Open a new Claude Code session
Sipcode picks up automatically on the next tool call Claude makes. No restart needed in most cases. To be safe, you can close any existing Claude Code window and open a fresh one.
Now Claude Code will be using Sipcode in the background.
Step 5. After about an hour of work, check it
sipcode drift
sipcode proxy --stats
If drift says "no drift" and proxy --stats shows a few dozen rewrites with savings, everything is working.
Updating Sipcode
Sipcode never checks for updates on its own. That would require a network call, and zero network calls in normal use is a guaranteed property of the codebase (a test fails the build otherwise). Updating is always a manual, explicit step.
To update to the latest version:
npm i -g sipcode@latest
Or use the built-in helper:
sipcode update # prints your current version + the update command
sipcode update --run # runs the update in place for you
After updating, confirm with sipcode --version and see what changed in the CHANGELOG. The MCP config never needs re-pasting; Claude asks the server for its tools on every reconnect, so new tools appear automatically.
Release cadence: patch releases ship whenever a fix or improvement is ready, often within a day or two of a reported issue. Since Sipcode can't notify you (zero network calls), a good habit is to run sipcode update about once a week. It's a one-second check, and --run upgrades you on the spot if something's new. Watch or star the repo to catch releases too.
What you get
| Feature | What it does for you |
|---|
| Context-rot detection | Warns when your Claude Code session is starting to behave worse than your norm |
| Re-read deduplication | Catches duplicate file reads and skips them, saving tokens and time |
| Compression-integrity scoring | For every saving, tells you what percentage of the original signal was kept |
| Spend telemetry | Daily, monthly, projected. All from your own transcripts (Claude Code and Codex), no cloud upload |
| Codex limits | When you will hit your Codex limit, what used it, and whether it may have shrunk |
| Regression check | Whether a Claude Code or Codex update changed cache or limit behaviour, pinned to the version |
| Codex plugin | Ask Codex about your spend, limits and regressions in plain words |
| Task cost estimation | Predicts what a coding task will cost across Opus, Sonnet, and Haiku before you run it |
| Codebase health score | Rates your repo 0-100 on how easy it is for an AI agent to work in |
| MCP server | 16 tools registered for Claude Desktop, so you can ask Claude itself about your usage |
| Reproducible benchmark | A locked 20-task corpus that anyone can run and verify |
Frequently asked questions
Is it really free?
Yes. MIT license. No tracking. No telemetry sent to us. No paid tier. You can read every line of source code on GitHub.
Does it send my code anywhere?
No. Sipcode makes zero network calls during normal use. Everything runs locally on your machine. We have a privacy test that fails if any network code is imported into the source.
To make repeat runs fast, Sipcode keeps a few caches on your own disk under ~/.sipcode/ (token counts per session log for today and forecast, per-session metrics for drift). They never hold message text, are never uploaded, and are rebuilt automatically if you delete them. PRIVACY.md lists exactly what is stored and where.
How is it different from other context tools?
See the comparison page. The short version: Sipcode is the only one with a published reproducible benchmark, zero false-dedup by architecture, and mid-session install support.
What is "context rot"?
When Claude's context window fills up with stale, repeated, or off-topic information, the quality of its answers drops. Sipcode measures this with sipcode drift and removes most of the waste with the proxy hook.
Does it work with Cursor or other AI tools?
The proxy, hooks and rules work with Claude Code. Sipcode also reads OpenAI Codex session logs for spend analytics (stats, today, forecast, trend, impact, why, receipt, drift); see Codex for what works and what is not supported for Codex yet. Inside Codex itself, the Sipcode plugin answers spend, limit and regression questions (see Use Sipcode inside Codex). For Cursor, sipcode rules --agent cursor writes the output-compression rules to Cursor's rules file; Cursor's session logs are not read.
How do I update?
npm i -g sipcode@latest
Or run sipcode update to see your version and the command, or sipcode update --run to update in place. Sipcode never auto-checks for updates (zero network calls), so updating is always explicit. See the CHANGELOG for what changed.
How do I uninstall?
sipcode proxy --uninstall
npm uninstall -g sipcode
Commands
| Command | What it does |
|---|
sipcode init | Set up Sipcode in a project (manifest + CLAUDE.md + proxy hook) |
sipcode update | Show how to update to the latest version (or --run to update now) |
sipcode hygiene | Install Session Hygiene: read-once rules + context-pressure hooks |
sipcode rules | Install, switch, or inspect the output-compression rules in CLAUDE.md |
sipcode manifest | Generate or refresh the project manifest |
sipcode drift | Check if the current session is drifting from your norm (--session, --here, --agent) |
sipcode proxy --stats | See what the proxy caught this session (also --install / --uninstall) |
sipcode benchmark | Run the locked 20-task corpus for a verifiable savings number |
sipcode estimate | Predict what a task will cost across models before you run it |
sipcode today | Today's spend summary vs your 30-day median |
sipcode stats | Cumulative token savings across all sessions (--html writes .sipcode/stats.html for Claude Code and .sipcode/stats-codex.html for Codex) |
sipcode forecast | Month-end spend projection from your last 14 days |
sipcode limits | Codex usage limits: when you run out at this pace, what used them, tokens per 1% over time |
sipcode regress | Did Claude Code or Codex get worse after an update? Each version against your other versions |
sipcode trend | Track one metric over time, to see if it's getting better |
sipcode why | Per-session forensics: where your tokens died |
sipcode impact | A/B compare your spend before vs after Sipcode |
sipcode score | Audit your repo for AI-friendliness (0-100, tiered badge) |
Run any of them with --help for full options.
Tip: which sessions do these report on? By default, why, stats, today, forecast, trend, impact, receipt and drift look across all your projects, not just the folder you are standing in. So if you run sipcode why inside project A but project B had the most recent activity, you will see project B. To scope any of them to the project you are currently in, add --here (for example, sipcode why --here or sipcode today --here). The same goes for Codex sessions. Use sipcode why --list to see every session and pick a specific one with --session <id>.
Requirements
- Node.js 20 or newer. Node.js 22.15 or newer to read the session logs Codex compresses (
.jsonl.zst); on an older Node.js they are skipped, with a warning at the top of each report.
- Claude Code installed (for the proxy hook). Sipcode also works as standalone CLI tools (benchmark, score, etc.) without Claude Code installed.
- Optional: OpenAI Codex CLI, for Codex spend analytics.
License
MIT. See LICENSE.
Acknowledgments
Built with care for the indie developers who burn through their Claude Max plan in two hours. The 62.6% benchmark methodology is documented in benchmark/METHODOLOGY.md. Anthropic's published research on context-window quality informs the integrity-scoring approach.
