Documentation

Everything you need to run billion-context locally and connect your agents. Exhaustive references live in the repository: CONFIGURATION.md, TECHNICAL-NOTES.md, PLUGIN.md, SESSION-IDENTITY.md.

Quickstart

One npm package, Node 22+. Install it, then start the local compression proxy:

npm install -g billion-context --prefix=~/.local   # Node 22+ (nvm / Homebrew / Windows: drop --prefix)
bili                                               # start the proxy (or: bili pi / claude / codex / omp / … to launch an agent through it)

Everything binds loopback only — nothing is exposed externally. Every instance serves the same built-in dashboard under its own address:

http://127.0.0.1:8787/__bili/

Next stop: the panel below — configuration, session stats, and live logs all live there.

Web UI

Access: open http://127.0.0.1:8787/__bili/ once the proxy is up — every instance serves this same built-in dashboard on its own loopback address (ACP_PORT overrides). Or just type /acp in your agent — the panel footer carries a direct link to the current session.

Every running instance serves a built-in dashboard at /__bili/:

• Overview — total sessions and requests, gross and net savings, global hit rate with miss breakdown, protocol distribution.
• Sessions — usage cards, context trajectory chart, cache economics with fold detail, compression blocks, and the Markdown handoff document (copy or download).
• Configuration — view and edit the JSON config; changes apply immediately.
• Connect — per-instance wiring guide with copyable commands.
• Logs — live tail of the daemon log, filterable by session id or keyword, downloadable as plain text.

Connect clients

Three ways to put the proxy between your agent and the model. Pick whichever fits your client:

Native plugin — recommended

Installs a thin plugin straight into the client (the original file is backed up once); deepest integration, with native in-conversation tools. Covers pi · omp · claude · codex · opencode · dsh · kimi · hermes · zcode:

Click any command chip to copy it.

For opencode, bili plugin install opencode --with-mcp also registers its MCP tools.

Launcher — works for any agent

Zero config edits: wraps any CLI agent and injects the proxy + compression state automatically. Each launch brings up a fresh throwaway proxy instance:

bili pi        # or: bili codex / claude / omp / opencode / hermes /
dsh / codebuddy / qoder / trae / jcode / kimi / gemini / iflow /
qwen / mcode / aider / copilot / amp / goose      (full list: bili --help)

Your own arguments pass straight through: bili pi -r.

Generic proxy — URL prefix routing

Any client that accepts a custom endpoint works out of the box: point its base URL at the prefix below, keeping the original upstream address as the tail:

http://localhost:8787/bili/https://api.openai.com/v1   # example

Replace the trailing https://api.openai.com/v1 with each client's original upstream address — see the table below for exactly where to put it.

Per-client integration detail:

Clients that hard-code HTTPS upstreams are handled by an automatic certificate: domains the client reaches are whitelisted on first sight. Need another host? Add it explicitly:

bili pi --mitm-domain api.foo.com

Commands

bili

Start the standalone proxy daemon (default port 8787).

bili <client>

Bring up a throwaway proxy + launch the chosen client against it — no config edits.

bili plugin install|list|update|remove

Manage the per-client plugins and their update lanes.

bili test pi

Non-polluting smoke test through the proxy.

bili export [session] [--full]

List sessions, or export one as a Markdown handoff document (--full restores original messages).

bili doctor

Audit every install lane: versions, owners, running proxies (read-only).

bili update

Check for and install a newer version now.

/acp

Live context panel inside your agent — includes this session's web-dashboard link.

/acp-cache

Token economics report for the session: new content vs cache hits vs compression repay.

Configuration

Everything lives in one JSON file, created automatically on first run and hot-reloaded while you edit:

~/.config/billion-context/billion-context.json     # { } is valid — defaults cover most setups

Configure it in the panel instead of by hand: the configuration page (here on a launcher agent's instance) validates every edit, offers quick-config controls, and writes this same file — environment variables still win over it when set.

Full parameter reference

Every knob in detail. Generated from the same seed as the repository's CONFIGURATION.md (CI drift-guarded), so the site and the repo docs stay one copy.

compress — every knob

• absorb — opt-in instant distillation of large tool results into short abstracts; originals go to the content store (enabled, minToolTokens (default 1000), contextThresholdPct, excludeTools, toolName "absorb").
• ccr — content cache & retrieve: large outputs are stored losslessly beside the session and replaced by a head excerpt plus pointer; the model fetches originals back via acp_retrieve. No cap or eviction; on by default in proxy mode since v2 (enabled, minToolTokens (~4000), excludeTools, toolName "acp_retrieve", maxHeadChars).
• search — search-behavior settings for search_context; currently holds planAware.
• search.planAware — off by default: when on, search_context candidates are re-ranked against current plan state (latest-wins todos + last user turn); off keeps byte-identical lexical results.
• imageCompression — opt-in lossy downscale via optional sharp before sending (enabled, minTokens 512, maxDimension 1280, quality 80, format "webp"); image_full restores originals; proxy mode only.
• prompts — override the kernel doctrine texts (compressPhilosophy, howToCompressRules, tier2DistillRules, tier3CondenseRules); load-bearing for quality — gated behind acknowledgePromptsRisk.
• reasoningGuard — auto-repair of reasoning-lattice truncation on gpt-5.x/6.x (≤3 continue-nudge rounds, marker "Continue thinking...") (enabled, maxContinue, maxTierN, markerText, base, offset, debugLog).
• outputSteering — { enabled? false, verbosityLevel? 2 (0–4), effortRouting? }: appends a conciseness directive to the system-prompt tail; clamps mechanical continuation requests.
• priceProfile — w / r / q ratios normalized to the input price (write / cache-read / output); unset ⇒ models.dev $/Mtok registry rows, kernel fallback {1, 0.1, 4}. Report-only — never affects triggers or the wire.
• acknowledgePromptsRisk — must be true before custom prompts take effect.

providers — route table fields

Keys are upstream URL prefixes — longest match wins, boundary-safe. https:// keys match /bili/ traffic; mitm:// keys match login-client traffic on the MITM lane. An entry with no fields is still an ordinary compressed lane.

Other top-level fields

• Server & core
• port — listen port (default 8787).
• host — bind address (default 127.0.0.1; "::" is dual-stack, 0.0.0.0 exposes outward).
• sessionHeader — HTTP header carrying the session id (default x-acp-session).
• log — file logging master switch (on by default).
• logFile — explicit path for bili.log (env ACP_LOG_FILE wins).
• debug — verbose per-request logging.
• dumpSse — raw SSE stream dump level for debugging.
• passthrough — global raw-relay switch (off by default; ACP_PASSTHROUGH / --passthrough win over the file).
• Upstream & billing
• upstream — fallback upstream base URL (ACP_UPSTREAM overrides).
• proxy — global outbound proxy. Resolution: per-route → BILI_UPSTREAM_PROXY → Web UI → this value → HTTP(S)_PROXY env → Windows system proxy → direct. Empty string = explicitly direct; SOCKS5 is rejected.
• modelContextLimit — legacy global window ceiling (default 200000); prefer compress.modelContextLimit.
• imageBilling — global image-token estimation: "auto" (default → pixels), "pixels" or "bytes" (explicit opt-in for byte relays).
• imageTokenCap — global per-image token cap; unset = uncapped (BILI_IMAGE_TOKEN_CAP wins, read live).
• Behavior toggles
• rollout — canary gating: features enable for a percent of installs, bucketed on a stable per-machine UUID; nested base rolls B out only inside A's cohort.
• maskHosts — mask non-public host names in logs as <private-host> (on by default; credentials are always masked).
• subagentSplit — Claude subagents get their own session namespace (on by default).
• forkAdoption — adopt anonymous forks into their parent session (off by default).
• affinitySimhash — simhash chain-alignment re-attaches sessions after pervasive client rewrites (on by default).
• resumeInheritance — inherited refs/blocks on resume (cc --resume) (on by default).
• chainContentDetection — recognize bili-owned traffic by body content (off; false-positive risk).
• chainEgressStamp — model-visible stamp on egress messages (off; burns tokens).
• stableSystemAnchor — best-effort wire-layer prefix-cache anchor (off; plain-proxy lanes).
• compat — wire-compatibility block: role remaps, stream error shape, strict-schema field drops, cache-control handling.
• MITM lane
• providersPath — external routes file path (env ACP_PROVIDERS beats both it and inline providers).
• mitm.enabled / mitm.domains — HTTPS interception switch and whitelist domains for login clients.
• mitm.handshakeTimeoutMs — TLS handshake timeout (default 10000).
• Process blocks
• network — transport timeouts & replays: upstreamTimeoutMs 720000 · requestWatchdogMs 2× · replayRetryMax 3 · replayRetryBaseMs 1500 · keepAliveTimeoutMs 5000 · clientErrorBackstopMs 30000 · exposureLogIntervalMs 3600000 · streamKeepAliveMs 15000 · preflightHoldMs 30000 · preflightDeadEndCooldownMs 300000 · proxyKeepAliveMaxMs 55000.
• persist — session persistence to disk: enabled true · zstd false · debounceMs 500 · tailTokens 16384 · epermAlertThreshold 5 · epermAlertRepeatMs 0.
• storage — unified storage sidecar: unified legacy — file tier selects the lane-wide storage mode; env BILI_STORAGE_UNIFIED wins when set.
• sessions — max 256 (LRU) · gc { enabled false, maxAgeDays 7, maxTokens 1000000, intervalMs 3600000 } — GC is opt-in; user data is never pruned silently.
• plugin.snapshotCapBytes — fork API snapshot cap (default 100 MiB; 0 disables snapshots).
• update — self-update channel: registry "npmjs" · checkIntervalMs 180000.
• Diagnostics & updates
• diagnostics — local troubleshooting knobs: dumpBody false · dumpReq true · rawDumpDir · dump4xx false (+MaxBytes 2 MiB) · renderNone/noInjectTool/noCompressPrompt false · countTokensPassthrough false · compressProtocol "tools".
• fakeCompletion — retry loop for truncated final chunks: retries 0 (opt-in) · bufCapBytes 16 MiB.
• autoUpdate — automatic version checks (on by default; disable via ACP_AUTO_UPDATE=0 or --no-auto-update).
• autoRestartOnUpdate — restart the daemon automatically once a newer version is installed (opt-in).
• updateTag — npm dist-tag channel: latest (default), dev, or pr.
• advisoryCheck / advisoryUrl — critical-defect advisory watcher (on by default; force-installs the recommended fix when your version is affected).
• releaseNotesCheck / releaseNotesUrl — release-notes feed for the panel (on by default; fetch + cache only, never installs).
• Advanced scalars
• codexCompact — intercept | pass (default intercept): handle Codex's compaction requests in bili or forward upstream — explicit forms plus the inline auto-compact transiting as an ordinary turn (prompt-form detection, #3008; overridden compact_prompt transits verbatim).
• ccrRetrievalTtlMs — lifetime of CCR retrieval pointers (default 600000; 0 disables retrieval).
• decompressTmpCap — size cap for temporary decompressed blocks (default 50).
• native.attachExternal — let launcher-less native plugins attach to an external daemon (off by default).

Environment variables win over the config file — precedence: env > file > built-in default, and a set variable owns the knob even if its value looks invalid. Common ones:

ACP_PORT=8787                    # listen port
ACP_HOST=127.0.0.1               # bind address
ACP_UPSTREAM=https://api.anthropic.com # fallback upstream base URL
ACP_PASSTHROUGH=1                # force passthrough on (wins over file)
ACP_PROVIDERS=/path/to/routes.json # external routes file (beats inline)
BILI_CONFIG_FILE=~/.config/...   # override the config file path
BILI_SESSIONS_DIR=~/.local/share/... # where session records are stored
BILI_UPSTREAM_PROXY=http://host:port   # outbound egress proxy
ACP_MODEL_CONTEXT_LIMIT=200000   # global context window override
BILI_MITM_DOMAINS=api.foo.com    # add MITM whitelist domains
BILI_REPLAY_RETRY_MAX=3          # transport-failure replays
BILI_SESSION_GC=1                # enable session garbage collection
BILI_IMAGE_TOKEN_CAP=8192        # per-image token budget
BILI_SUBAGENT_SPLIT=0            # disable subagent session split
BILI_FORK_ADOPTION=1             # adopt anonymous forks into parent session
ACP_LOG_FILE=/path/to/bili.log   # explicit log path
ACP_COMPRESS_TOOL=0              # disable the injected compress tool
ACP_COMPRESS_NUDGE=0             # disable growth nudges

How compression works

The same four mechanisms as the front page, condensed:

• Folded, not rewritten When history outgrows its budget, only the newly consumed slice is folded into a compact summary block — once, per block. The window oscillates in a bounded band instead of growing without limit: production sessions run months at ten-thousand-plus calls. Any block decompresses back to full text when you need the detail.
• The provider's cache stays warm A fold deactivates old ranges without touching the front of the conversation, so the prompt-cache prefix survives turn after turn — 94.2% of active input was served from cache in the study. Rewrite-style compaction invalidates the whole prefix and re-bills it. This does not.
• The model decides what to forget A versioned compression doctrine lives in the system prompt; a growth-gated nudge says when folding pays off. The agent judges what the task still needs, may refuse, and compresses between steps — never mid-step.
• Every token is accounted Each request is sampled into a per-session ledger — new content, cache reads, compression repay, TTL expiry — plotted in percentage points on a trajectory chart. Audit real savings with /acp in the terminal or the built-in web UI at /__bili/.

The full treatment, with numbers: read the preprint.

Privacy

billion-context runs only on your machine and binds loopback by default. It forwards model traffic — OAuth tokens pass through untouched, unauthenticated probes aside — and uploads nothing.

Session records stay local (~/.local/share/billion-context/sessions); the log sits beside the state dir. Export any session with bili export, delete files whenever you like.

FAQ

Resources

• billion-context — GitHub
• acp-kernel — the compression kernel
• npm package
• Paper / preprint
• QQ: 1056132097 / 1108730198