Quick Start

A minimal path from clone to a verified running session. You will have LightRSI installed with TokenPilot active in under 5 minutes.

1. Clone and Build

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

The last command installs the lightrsi CLI entrypoint at ~/.local/bin/lightrsi. Make sure ~/.local/bin is on your PATH.

2. Pick Your Host

Choose your agent host and run the matching install command:

OpenClaw

pnpm component:install:tokenpilot:openclaw

Codex

npm --prefix components/tokenpilot/adapters/codex run build
npm --prefix components/tokenpilot/adapters/codex run install:codex

Claude Code

npm --prefix components/tokenpilot/adapters/claude-code run build
npm --prefix components/tokenpilot/adapters/claude-code run install:claude-code

Each install command:

• Updates the host's configuration files
• Enables the TokenPilot plugin
• Sets the default normal runtime mode
• Registers required hooks or MCP servers
• Creates backups of modified files as .tokenpilot.bak

3. Start a Session

Open or restart your host, then start a new session.

OpenClaw

Use a lightrsi/<model> model like lightrsi/gpt-5.4-mini
Run: /lightrsi status

Codex

Start Codex normally, approve TokenPilot hooks if prompted
Open a new session so SessionStart can start the proxy

Claude Code

Start Claude Code normally
Open a new session so SessionStart can start the gateway

4. Verify It Works

Run the doctor command to confirm everything is healthy:

OpenClaw

/lightrsi doctor
# Or outside OpenClaw:
lightrsi openclaw doctor

Codex

lightrsi codex doctor

Claude Code

lightrsi claude-code doctor

Expected output:

• plugin entry enabled
• config enabled
• mode normal
• stabilizer enabled
• reduction enabled
• proxy healthy: yes

5. See Your Savings

After a few turns, check your report:

OpenClaw

/lightrsi report

Codex

lightrsi codex report

Claude Code

lightrsi claude-code report

If you see token and cost metrics instead of "No TokenPilot session stats yet", TokenPilot is actively managing your context.

6. Visual Inspector

Open the built-in visual inspector to see your session in real time:

lightrsi visual

This opens a browser view showing stable-prefix, reduction, and eviction snapshots.

What's Next

• Install Your First Plugin — detailed install walkthrough
• Runtime Modes — choose conservative, normal, or aggressive
• CLI Reference — all commands and flags