sipcode

<p align="center">
  <a href="https://anuj7411.github.io/sipcode/" aria-label="Sipcode">
    <img src="https://raw.githubusercontent.com/Anuj7411/sipcode/main/docs/brand/icon/icon-color.png" alt="Sipcode" width="120" />
  </a>
</p>

<h1 align="center">Sipcode</h1>

<p align="center">
  <strong>Keep Claude Code's context clean for sharper answers and lower cost, automatically.</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/sipcode"><img src="https://img.shields.io/npm/v/sipcode?color=5B4FCF&label=npm" alt="npm" /></a>
  <a href="https://github.com/Anuj7411/sipcode/stargazers"><img src="https://img.shields.io/github/stars/Anuj7411/sipcode?color=5B4FCF&label=stars" alt="GitHub stars" /></a>
  <a href="https://www.npmjs.com/package/sipcode"><img src="https://img.shields.io/npm/dm/sipcode?color=5B4FCF&label=downloads" alt="npm downloads per month" /></a>
  <a href="https://github.com/Anuj7411/sipcode/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-5B4FCF" alt="MIT licensed" /></a>
  <img src="https://img.shields.io/badge/tests-1%2C996%20passing-28C840" alt="1996 tests passing" />
  <img src="https://img.shields.io/badge/network%20calls-0-2D3142" alt="zero network calls" />
</p>

<p align="center">
  <a href="https://anuj7411.github.io/sipcode/">Website</a> · <a href="https://anuj7411.github.io/sipcode/compare/">Compare</a> · <a href="https://github.com/Anuj7411/sipcode/releases">Releases</a>
</p>

---

## Install in 30 seconds

```bash
npm i -g sipcode
sipcode init
```

That is it. Your next Claude Code session will use Sipcode automatically. Verify a few minutes later:

```bash
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](#updating-sipcode).

---

## What is Sipcode?

Sipcode is a free command-line tool that sits between you and Claude Code. It does three things:

1. It watches Claude Code's context window and warns you when it starts to bloat (we call this "context rot")
2. It catches duplicate file reads and other waste before they reach Claude, so you pay less for the same answers
3. 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** | ✓ 15 tools | ✗ | ✗ | partial |
| **Agents covered** | Claude Code (all features); OpenAI Codex (spend analytics only, 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](https://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](benchmark/METHODOLOGY.md)).

```
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 only: Sipcode reports what your Codex sessions used and where the tokens went. It does not change what Codex does.

**Commands that read Codex:** `stats`, `today`, `forecast`, `trend`, `impact`, `why`, `receipt` and `drift`, plus the session tools in the MCP server (they take an optional `agent` input: `"claude-code"` or `"codex"`).

- `--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`](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](https://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 (`.jsonl.zst`) are skipped, and a note says how many.

---

## How to install (more detail)

Sipcode works on Mac, Linux, and Windows. You need Node.js 20 or newer.

### 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](https://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](https://nodejs.org/)

Verify it worked:

```bash
node --version
```

You should see `v20.0.0` or higher.

### Step 2. Install