billion-context: Keep Long Claude Code Sessions From Forgetting

An open-source plugin that folds old chat history into summaries you can unfold later, so long coding sessions keep their details.

When a Claude Code session fills its context window, it gets compacted into one summary and small details can get lost. billion-context is an open-source project that takes a different approach: it compresses older parts of the chat a little at a time and lets the model reopen them when it needs the exact detail. Here is what it really does and how to install it.

What you need

• Claude Code (or another supported agent such as Codex, OpenCode or pi).

• Node.js and npm. The project's Docker notes say its built-in SQLite engine needs Node 22 or newer, so use a recent Node version.

• The billion-context repo: github.com/ranxianglei/billion-context. It is free and open source.

How it works

billion-context runs as a small local proxy between your agent and the model API. It gives the model four extra tools:

• compress: folds a range of older messages into a detailed summary.

• decompress: unfolds a range again when the exact wording is needed.

• search_context: keyword search over the summaries and visible messages.

• acp_status: shows how full the context is and what can still be folded.

The model itself decides when and what to fold. The README says compression is incremental and reversible, so nothing is thrown away.

Step by step

1. Install the package. On Mac or Linux:

npm install -g billion-context --prefix=~/.local

If your terminal can't find the bili command afterwards, add ~/.local/bin to your PATH. On Windows, npm install -g billion-context works.

2. Pick one way to use it with Claude Code. Option A, the launcher (simplest), starts Claude Code through bili:

bili claude

Option B, the native plugin: inside Claude Code, run these three commands, then restart Claude Code.

/plugin marketplace add ranxianglei/billion-context
/plugin install billion-context@billion-context
/billion-context:bili-setup

3. Optional: check the proxy is running.

curl -s http://localhost:8787/__bili/health

4. Work as normal. When you need something from earlier, ask for it directly:

Search your folded context for the decision we made about the database schema and quote the exact reasoning. If it's in a compressed range, decompress it first.

5. For Codex, the README lists bili codex (launcher) or bili plugin install codex. Other agents such as OpenCode, pi, Gemini CLI, Aider and Goose have launcher commands listed in the README.

6. To turn it off, run:

bili plugin remove claude

Good to know

• The numbers are the developer's own. The README's study reports 174,327 model calls and 18.76 billion input tokens over 4.5 months across three machines. That is total usage, not one single chat. The project describes "month-long single sessions" and also says you can run one session "for days". Treat these as the maker's claims, not independent tests.

• Cursor: the README names Cursor in its diagram but lists no Cursor install command.

• Claude desktop app: the README notes that the Code tab in the Claude desktop app bypasses the proxy, so use the terminal version.

• Security: the proxy has no authentication. Keep it on your own machine or a trusted network.

• Auto-updates: it checks npm for updates and advisories in the background. You can turn this off with "autoUpdate": false in its config if you prefer to update by hand.

• Early software: the main branch is a development branch and can break. The first fold may not happen until around 200K tokens with default settings.

• Costs: it doesn't make the model free. It aims to use fewer tokens, but you still pay for the model calls on your plan or API.

Sources

• billion-context on GitHub

• billion-context package page (termo.ai)

Found this useful? Follow @kevinsingh.me on Instagram for a new AI tool every day, and subscribe so you don't miss the next one.