A modular runtime for recursive improvement in long-running LLM agents

---

🛠️ Products

Context Cleaner

Context Cleaner is available on OpenClaw, Codex, Claude Code, and DeepSeek Harness, with the same plan, approval, status, and cancellation model across hosts. In Codex, /lightrsi-clean opens the host-rendered task selector; the direct terminal equivalent is lightrsi codex clean. Analysis is read-only until you confirm a selection, and protected tasks cannot be selected. The pi and OpenCode adapters do not integrate Context Cleaner yet.

📄 Papers

LightRSI separates reusable improvement capabilities from shared runtime infrastructure and host-specific integration. TokenPilot is the first preset.

Papers	What It Does	How It Works	Effect
TokenPilot	Keeps long-running agent sessions smaller, cheaper, and easier to sustain	Stabilizes the reusable prompt prefix, trims oversized tool output before it poisons later turns, and limits how much old context is carried forward as sessions grow	Better cache reuse, lower token usage, lower cost, and less context bloat in shared sessions

📑 Table of Contents

• 📢 News
• 🛠️ Products
• 📄 Papers
• 🔧 Installation
• ⚡ Quick Start
• 🖼️ Visual Results
• 🏗️ Architecture
• 🧪 Experiment Reproduction
• 💡 Commands
• 📁 Experimental Results
• 📄 Citation
• 🤝 Contributing
• 🎉 Contributors
• 📚 Related Works
• 💬 Community

📢 News

• [2026-10-02]: 🧩 TokenPilot now supports OpenCode and pi.
• [2026-09-16]: 🚀 Context Cleaner, our first product, is now available, and TokenPilot now supports DeepSeek Harness.
• [2026-08-21]: 🎉🎉🎉 TokenPilot: Cache-Efficient Context Management for LLM Agents has been accepted by EMNLP 2026!
• [2026-06-28]: 🧩 TokenPilot now supports Codex and Claude Code. Demo video: YouTube · Bilibili
• [2026-06-16]: 🚀 TokenPilot: Cache-Efficient Context Management for LLM Agents is released.

🔧 Installation

1. Prepare the Repository Once

Clone the repository and build the shared packages:

git clone https://github.com/zjunlp/LightRSI.git
cd LightRSI
corepack enable
pnpm install

The Host-specific Cleaner installer below builds the shared CLI, recovery MCP, and selected adapter before installing them. A separate repository-wide build is not required for this flow.

2. Pick Your Host

Host	Integration mode	Install entry
OpenClaw	bundled plugin + embedded runtime	pnpm component:install:tokenpilot:openclaw
Codex CLI	hooks + local Responses proxy	corepack pnpm cleaner:install:codex
Claude Code	gateway routing + observability hooks	corepack pnpm cleaner:install:claude-code
OpenCode	in-process plugin + recovery MCP	npm --prefix components/adapters/opencode run install:opencode
pi	in-process extension + native recovery tool	npm --prefix components/adapters/pi run install:pi
DeepSeek Harness	native Cordis plugin	build the adapter package, then plugin add in the Harness checkout

Open the host you want and run the default install commands.

OpenClaw

Default install:

pnpm component:install:tokenpilot:openclaw

This installs the current TokenPilot OpenClaw adapter, updates ~/.openclaw/openclaw.json, enables the plugin, switches plugins.slots.contextEngine to layered-context, applies the default normal mode, and tries to restart the OpenClaw gateway automatically.

If your OpenClaw home or config path is not under the default ~/.openclaw, set:

export LIGHTRSI_OPENCLAW_HOME="/path/to/openclaw-home"
export OPENCLAW_CONFIG_PATH="/path/to/openclaw.json"

Then run the same install command again:

pnpm component:install:tokenpilot:openclaw

Codex CLI

Default install:

corepack pnpm cleaner:install:codex

This builds and installs the shared CLI, recovery MCP, Codex adapter, and the explicit-only lightrsi-clean, lightrsi-clean-status, lightrsi-clean-apply, and lightrsi-clean-cancel command skills. It keeps your current active Codex provider, reroutes it through the local TokenPilot proxy, writes ~/.codex/tokenpilot.json, and registers the required hooks and MCP server.

If your Codex config files are not under the default ~/.codex, set:

export CODEX_CONFIG_PATH="/path/to/config.toml"
export CODEX_HOOKS_CONFIG_PATH="/path/to/hooks.json"
export TOKENPILOT_CODEX_CONFIG="/path/to/tokenpilot.json"

Then run the same install flow:

corepack pnpm cleaner:install:codex

On Windows, the installer uses the npm command directory when that directory is already on PATH and creates lightrsi.cmd. On Linux/macOS it installs under ~/.local/bin by default. Set LIGHTRSI_BIN_DIR to choose another command directory.

Claude Code

Default install:

corepack pnpm cleaner:install:claude-code

This builds and installs the shared CLI, recovery MCP, Claude Code adapter, and the explicit-only Cleaner analysis, status, apply, and cancel command skills. It updates local gateway routing, registers the required hooks and MCP server, and preserves existing Claude files as .tokenpilot.bak backups before rewriting.

If your Claude Code files are not under the default ~/.claude, set:

export CLAUDE_CODE_SETTINGS_PATH="/path/to/settings.json"
export CLAUDE_CODE_MCP_CONFIG_PATH="/path/to/.claude.json"
export TOKENPILOT_CLAUDE_CODE_CONFIG="/path/to/tokenpilot.json"

Then run the same install flow:

corepack pnpm cleaner:install:claude-code

Use node scripts/install-cleaner.mjs <host> --dry-run to inspect the exact build and installation commands without changing Host configuration. Add --skip-build only when reusing an existing local build; the installer rejects missing or older CLI, MCP, and adapter artifacts before changing Host configuration.

OpenCode

The OpenCode adapter is an in-process v1 plugin plus the shared recovery MCP server, so no proxy or gateway is involved.

pnpm install
pnpm --filter @lightrsi/mcp build                   # recovery MCP server
npm --prefix components/adapters/opencode run build
npm --prefix components/products/cli run build      # for the lightrsi CLI
npm --prefix components/adapters/opencode run install:opencode

Install writes plugins/tokenpilot.js and a single mcp.tokenpilot_memory_fault_recover entry under the OpenCode config dir ($XDG_CONFIG_HOME/opencode, default ~/.config/opencode), backing up any file it replaces. If you keep an opencode.jsonc, or a opencode.json that is not plain JSON, the installer leaves it untouched and prints the MCP snippet for you to paste, so your comments are never lost. Set TOKENPILOT_OPENCODE_CONFIG_DIR to use another config dir.

Uninstall removes only what install added:

npm --prefix components/adapters/opencode run uninstall:opencode
npm --prefix components/adapters/opencode run uninstall:opencode -- --purge   # also created config and state

pi

The pi adapter is an in-process extension, so no proxy or gateway is involved and no pi-owned config file is modified.

pnpm install
npm --prefix components/adapters/pi run build
npm --prefix components/products/cli run build      # for the lightrsi CLI
npm --prefix components/adapters/pi run install:pi

Install writes ~/.pi/agent/extensions/tokenpilot/index.js, a loader that pi auto-loads (any pre-existing file at that path is backed up first), and ~/.pi/agent/tokenpilot.json, which never contains credentials. PI_CODING_AGENT_DIR and TOKENPILOT_PI_CONFIG are honoured.

Uninstall removes the loader and restores any backup:

npm --prefix components/adapters/pi run uninstall:pi
npm --prefix components/adapters/pi run uninstall:pi -- --purge   # also created config and state

DeepSeek Harness

The DeepSeek Harness adapter is a native Cordis plugin and is installed into a DeepSeek Harness checkout rather than through the shared CLI. Build a local package from this repository:

corepack pnpm --filter @lightrsi/deepseek-harness-adapter build
corepack pnpm --filter @lightrsi/deepseek-harness-adapter pack --pack-destination ./artifacts

From the DeepSeek Harness checkout, add the generated .tgz to the profile you use, such as web:

node --import tsx/esm apps/cli/src/bin.ts plugin --profile web add /absolute/path/to/lightrsi-deepseek-harness-adapter-<version>.tgz

The plugin is registered as tokenpilot-dsh and is disabled by default. Configure and enable it only after supplying a durable stateDir and the estimator and eviction settings required by your Harness profile. Its failure mode is fail-open, so an optimization failure does not block the agent.

⚡ Quick Start

Pick your host and open the matching one-pass setup below.

OpenClaw

1. Start or restart OpenClaw.
2. Open a session with a lightrsi/<model> model such as lightrsi/gpt-5.4-mini.
3. Run:

/lightrsi status

You should see a status block similar to:

• plugin entry enabled
• config enabled
• mode normal
• context engine slot layered-context
• stabilizer enabled
• reduction enabled

For a fuller runtime summary, run:

/lightrsi report
/lightrsi doctor
/lightrsi visual
/lightrsi mode normal

/lightrsi doctor is the quickest integration self-check for the current OpenClaw adapter surface. /lightrsi visual opens the local visual inspector for stability, reduction, and eviction snapshots. /lightrsi mode <conservative|normal|aggressive> switches preset runtime behavior.

You can also use the standalone CLI outside OpenClaw:

lightrsi openclaw status
lightrsi openclaw report
lightrsi openclaw doctor
lightrsi openclaw visual
lightrsi openclaw mode normal

Codex CLI

The current Codex path uses the standalone CLI plus Codex hooks.

1. Run the Codex install flow shown above.
2. Start Codex normally.
3. If Codex asks you to review or trust the installed TokenPilot hooks, approve them.
4. Open a new Codex session so SessionStart can start the local proxy.
5. In another terminal, verify the adapter:

lightrsi codex status
lightrsi codex doctor
lightrsi codex report
lightrsi codex mode normal
lightrsi codex reduction status
lightrsi codex stabilizer target user

Expected first-run shape:

• lightrsi codex doctor reports proxy healthy: yes
• lightrsi codex status shows stabilizer and reduction enabled
• after a few turns, lightrsi codex report no longer says No TokenPilot session stats yet.

Install success does not always mean the proxy is already running before the first trusted session. If doctor still reports proxy healthy: no after trusting hooks and opening a new Codex session, use the manual fallback:

tokenpilot-codex status
tokenpilot-codex start

Claude Code

The current Claude Code path also uses the standalone CLI, but routes requests through a local Anthropic-compatible gateway and a shared MCP recovery server.

1. Run the Claude Code install flow shown above.
2. Start Claude Code normally.
3. Open a new Claude Code session so SessionStart can auto-start the local gateway.
4. In another terminal, verify the adapter:

lightrsi claude-code status
lightrsi claude-code doctor
lightrsi claude-code report
lightrsi claude-code mode normal
lightrsi claude-code reduction status
lightrsi claude-code stabilizer target developer

Expected first-run shape:

• lightrsi claude-code doctor reports proxy healthy: yes
• lightrsi claude-code status shows stabilizer and reduction enabled
• after a few turns, lightrsi claude-code report no longer says No TokenPilot session stats yet.

Like Codex, install success does not guarantee that the gateway is already healthy before the first real session triggers SessionStart.

OpenCode

The current OpenCode path uses the in-process plugin plus the shared recovery MCP server.

1. Run the OpenCode install flow shown above.
2. Restart OpenCode so the plugin and the MCP server load.
3. Verify the adapter:

lightrsi opencode status
lightrsi opencode doctor
lightrsi opencode report
lightrsi opencode mode normal
lightrsi opencode eviction status

Expected first-run shape:

• lightrsi opencode doctor reports the loader, the bundle, and the MCP entry present, with the MCP probe ok
• after a few turns, lightrsi opencode report has session data
• config edits, including lightrsi opencode mode ..., apply on the next request without restarting OpenCode

TokenPilot never changes OpenCode's native compaction.prune setting; lightrsi opencode doctor reports it as native tool-output pruning: on|off.

pi

The current pi path uses the in-process extension, with recovery available as a native tool because pi has no MCP.

1. Run the pi install flow shown above.
2. Start pi, or run /reload in a running session, so the extension loads.
3. Verify the adapter:

lightrsi pi status
lightrsi pi doctor
lightrsi pi report
lightrsi pi mode normal
lightrsi pi eviction status

Expected first-run shape:

• lightrsi pi doctor reports the loader and bundle present, a writable state dir, and declared features: stabilizer, reduction, eviction
• after a few turns, lightrsi pi report has session data
• no pi-owned file (settings.json, models.json, auth.json) is modified

DeepSeek Harness

After adding and enabling the tokenpilot-dsh Cordis plugin, open a DeepSeek Harness session and run:

/tokenpilot-status

The command reports estimator, scheduling, application, and deferral state without creating a model turn. By default, the adapter runs its eviction pass before the Harness's native compaction; preserve this ordering unless you deliberately change the profile configuration.

🖼️ Visual Results

The screenshots below come from the built-in visual inspector opened with:

lightrsi visual

TokenPilot runtime effects

Stable-prefix view:

Reduction view:

Eviction view:

🏗️ Architecture

The current public repository separates reusable capabilities, verified presets, host adapters, and user-facing products.

At a high level:

• components/packages
  • shared foundation and independently composable feature packages
• components/presets
  • verified feature combinations such as TokenPilot
• components/adapters
  • host-specific integration, install surfaces, runtime hooks, and product registration
  • OpenClaw, Codex, and Claude Code route requests through a local proxy or gateway; OpenCode and pi run in-process, so they need no proxy
• components/products
  • shared CLI, Visual launcher, recovery MCP, and interactive Cleaner surfaces

LightRSI/
├── components/
│   ├── packages/
│   │   ├── foundation/           # contracts, runtime, host, history, artifact, product infrastructure
│   │   └── features/             # stabilizer, reduction, eviction, and memory
│   ├── presets/
│   │   └── tokenpilot/           # Stabilizer + Reduction + Eviction composition contract
│   ├── adapters/
│   │   ├── openclaw/             # OpenClaw adapter
│   │   ├── codex/                # Codex CLI adapter
│   │   ├── claude-code/          # Claude Code adapter
│   │   ├── opencode/             # in-process OpenCode plugin + recovery MCP
│   │   ├── pi/                   # in-process pi extension + native recovery tool
│   │   ├── deepseek-harness/     # native DeepSeek Harness Cordis adapter
│   │   └── shared/               # code shared by the in-process adapters
│   └── products/
│       ├── cli/                  # shared lightrsi CLI, browser visual launcher, and Cleaner UI
│       └── mcp/                  # shared recovery and interactive MCP session support
├── docs/                         # Public-facing notes and smoke helpers for the current runtime path
├── website/                      # Documentation site
└── README.md

TokenPilot is now a preset rather than a source-code parent directory. Each adapter explicitly binds the preset and contributes host discovery metadata; the shared CLI and Visual surface consume those registrations.

🧪 Experiment Reproduction

Benchmark tasks, runners, profiles, and analysis are maintained in the separate TokenPilot experiment repository. LightRSI contains the runtime and plugin platform; it no longer vendors the experiment harness.

Experiment entrypoints:

• TokenPilot reproduction guide

💡 Commands

Use the basic commands first, then the session-aware and advanced ones when you need them.

Shared standalone CLI patterns:

lightrsi report
lightrsi visual
lightrsi use openclaw
lightrsi use codex session <session-id>
lightrsi context
lightrsi <host> session <session-id> report

• lightrsi report shows the latest available report across hosts
• lightrsi visual opens the shared browser visual and lets you switch hosts and sessions
• lightrsi use <host> sets the default host for hostless CLI commands
• lightrsi use <host> session <session-id> pins the default session for later report and visual
• lightrsi context shows the current default host, pinned session, and remembered config target
• lightrsi <host> session <session-id> report reads one specific session directly

Pick your host for the command surface below.

OpenClaw

Inside an OpenClaw session:

/lightrsi status
/lightrsi report
/lightrsi doctor
/lightrsi visual
/lightrsi mode normal
/lightrsi stabilizer target developer
/lightrsi reduction mode balanced
/lightrsi eviction on
/lightrsi help

Outside OpenClaw, the standalone CLI supports the same host directly:

lightrsi openclaw status
lightrsi openclaw report
lightrsi openclaw doctor
lightrsi openclaw visual
lightrsi openclaw mode normal
lightrsi openclaw session <session-id> report

Useful OpenClaw-only controls:

• mode aggressive enables the most aggressive runtime policy preset
• eviction ... controls lifecycle-aware context eviction
• settings details on expands status output with more runtime detail
• stabilizer ... and reduction ... let you tune prefix stabilization and observation reduction directly

Codex CLI

Use the standalone CLI:

lightrsi codex status
lightrsi codex report
lightrsi codex doctor
lightrsi codex visual
lightrsi codex session <session-id> report
lightrsi codex reduction status
lightrsi codex stabilizer target developer
lightrsi codex mode normal
lightrsi codex reduction mode balanced
lightrsi codex help

Useful Codex controls:

• stabilizer on|off toggles stable-prefix rewriting
• stabilizer target <developer|user> chooses where dynamic context is attached
• reduction on|off toggles observation reduction
• reduction mode <light|balanced> switches between lighter and stronger trimming
• reduction pass toolPayloadTrim off disables one specific reduction pass
• lightrsi codex clean analyzes a session and interactively selects tasks to clean

Claude Code

Use the standalone CLI:

lightrsi claude-code status
lightrsi claude-code report
lightrsi claude-code doctor
lightrsi claude-code visual
lightrsi claude-code session <session-id> report
lightrsi claude-code reduction status
lightrsi claude-code stabilizer target developer
lightrsi claude-code mode normal
lightrsi claude-code reduction mode balanced
lightrsi claude-code help

Useful Claude Code controls:

• stabilizer on|off toggles stable-prefix rewriting
• stabilizer target <developer|user> chooses where dynamic context is attached
• reduction on|off toggles observation reduction
• reduction mode <light|balanced> switches between lighter and stronger trimming
• reduction pass toolPayloadTrim off disables one specific reduction pass

OpenCode

Use the standalone CLI:

lightrsi opencode status
lightrsi opencode report
lightrsi opencode doctor
lightrsi opencode visual
lightrsi opencode session <session-id> report
lightrsi opencode reduction status
lightrsi opencode mode normal
lightrsi opencode eviction status
lightrsi opencode help

Useful OpenCode controls:

• stabilizer on|off toggles stable-prefix rewriting
• reduction on|off toggles observation reduction
• reduction pass <name> on|off disables one specific reduction pass
• eviction on|off and eviction set minBlockChars <number> control opt-in lifecycle eviction
• mode aggressive is not exposed, as on Claude Code and pi

pi

Use the standalone CLI:

lightrsi pi status
lightrsi pi report
lightrsi pi doctor
lightrsi pi visual
lightrsi pi session <session-id> report
lightrsi pi reduction status
lightrsi pi mode normal
lightrsi pi eviction status
lightrsi pi help

Useful pi controls:

• stabilizer on|off toggles stable-prefix rewriting
• stabilizer target <developer|user> chooses where dynamic context is attached
• reduction on|off toggles observation reduction, and reduction mode <light|balanced|aggressive> switches trimming strength
• reduction pass <name> on|off disables one specific reduction pass
• eviction on|off and eviction set minBlockChars <number> control opt-in lifecycle eviction
• mode aggressive is not exposed

DeepSeek Harness

Inside a DeepSeek Harness session:

/tokenpilot-status

This read-only command reports estimator activity, eligible eviction work, scheduled or applied changes, and any deferrals. The DeepSeek Harness adapter is registered by Cordis as tokenpilot-dsh; it does not use the shared lightrsi CLI.

📁 Experimental Results

Benchmark tasks, runners, profiles, analysis, and result bundles are maintained in the separate TokenPilot experiment repository. This repository keeps only the runtime and plugin platform.

• TokenPilot reproduction guide
• PinchBench benchmark documentation
• Claw-Eval benchmark documentation

For the latest commands, configurations, and reported results, use the experiment repository as the source of truth.

📄 Citation

Please cite our paper if you use LightRSI in your work.

@article{xu2026tokenpilot,
  title={TokenPilot: Cache-Efficient Context Management for LLM Agents},
  author={Xu, Buqiang and Xue, Zirui and Chen, Dianmou and Fu, Chenyang and Wu, Chiyu and Huang, Caiying and Jiang, Chen and Fang, Jizhan and Deng, Xinle and Chen, Yijun and others},
  journal={arXiv preprint arXiv:2606.17016},
  year={2026}
}

🤝 Contributing

We welcome bug fixes, host adapter improvements, onboarding fixes, tests, and documentation updates, see CONTRIBUTING.md for more details.

🎉Contributors

We thank all the contributors to this project, more contributors are welcome!

📚 Related Works

LightMem Series

This repository belongs to ZJUNLP LightMem series, focusing on solving context bloat, excessive token consumption and low cache utilization for long-running LLM agents:

• LightMem — A lightweight and efficient memory management framework designed for Large Language Models and AI Agents
• LightMem-Ego — A lightweight streaming multimodal memory system for everyday-life assistance

Other Related Projects

• LLMLingua-2 — Token-level prompt compression
• SelectiveContext — Self-information-based context reduction
• Pichay — Demand paging for LLM context windows
• MemoBrain — Executive memory for long-horizon reasoning agents
• AgentSwing — Adaptive parallel context management routing for web agents
• MemOS — Memory operating system for LLM agents
• Headroom — Compresses everything when AI agent reads

💬 Community

• Discord — setup help, debugging, feedback, and user discussion
• GitHub Issues — reproducible bugs, feature requests, and integration regressions