TokenPilot Installation

TokenPilot is installed as part of installing your first plugin. This page covers TokenPilot-specific details.

Choose your host below. DeepSeek Harness uses the Harness profile plugin installer; OpenClaw, Codex, Claude Code, pi, and OpenCode use their host adapter installers.

Prerequisites

Before installing TokenPilot, complete Install LightRSI.

Install Commands

OpenClaw

pnpm component:install:tokenpilot:openclaw

Codex

corepack pnpm cleaner:install:codex

Claude Code

corepack pnpm cleaner:install:claude-code

DeepSeek Harness

# From the LightRSI repository
corepack pnpm --filter @lightrsi/deepseek-harness-adapter build
corepack pnpm --filter @lightrsi/deepseek-harness-adapter pack --pack-destination ./artifacts

# Then, from your DeepSeek Harness checkout
node --import tsx/esm apps/cli/src/bin.ts plugin --profile web add /absolute/path/to/lightrsi-deepseek-harness-adapter-<version>.tgz

pi

npm --prefix components/adapters/pi run build
npm --prefix components/adapters/pi run install:pi

OpenCode

npm --prefix components/adapters/opencode run build
npm --prefix components/adapters/opencode run install:opencode

What the Installer Does

For OpenClaw, Codex, and Claude Code, the host installation flow:

1. Builds the adapter for your host
2. Updates host configuration files with TokenPilot settings
3. Enables the plugin (sets enabled: true)
4. Sets default mode to normal
5. Registers hooks/MCP/proxy needed for runtime operation
6. Creates backups of modified files as .tokenpilot.bak

For OpenClaw, the release installer builds one archive containing both the native plugin and the bundled lightrsi CLI. It installs the CLI in ~/.local/bin by default (or LIGHTRSI_BIN_DIR when set) and provides the launchers required by the supported Windows, WSL, and Git Bash paths.

For pi and OpenCode, the adapter installers build the adapter, install a marker-tagged in-process loader, write tokenpilot.json in normal mode, and register the recovery surface: a native memory_fault_recover tool for pi (pi has no MCP), and the shared recovery MCP server in opencode.json for OpenCode. Neither installs a proxy or gateway, and neither creates .tokenpilot.bak backups.

For DeepSeek Harness, the package registers tokenpilot-dsh in the selected profile. Replace the archive path with your generated .tgz. The integration is disabled by default and requires a persistent stateDir plus estimator and eviction configuration before enabling it. Follow Configure and Enable; shared runtime modes and proxy installation do not apply.

Verify Installation

Run the verification command for your host:

OpenClaw

lightrsi openclaw doctor

Codex

lightrsi codex doctor

Claude Code

lightrsi claude-code doctor

DeepSeek Harness

/tokenpilot-status

pi

lightrsi pi doctor

OpenCode

lightrsi opencode doctor

For OpenClaw, Codex, and Claude Code, check:

• plugin entry enabled
• config enabled
• mode normal
• stabilizer enabled
• reduction enabled

For Codex and Claude Code, also check:

• proxy healthy: yes

For pi and OpenCode, doctor reports the loaded extension or plugin, the bundle, a writable state dir, and the declared features (stabilizer, reduction, eviction). OpenCode additionally probes its recovery MCP entry.

In DeepSeek Harness, run /tokenpilot-status inside a session. It reports estimator, scheduling, application, and deferral state without creating a model turn. See verification details.

Install with Custom Paths

If your host files are not in the default locations, set environment variables before running the install command. See Install Your First Plugin for the full list.

Failed Install?

Check Troubleshooting for common install problems, or DeepSeek Harness troubleshooting for profile and estimator setup. The backup restoration examples below apply to OpenClaw and Claude Code, not Harness profiles.

Quick recovery

# Restore from backups
cp ~/.openclaw/openclaw.json.tokenpilot.bak ~/.openclaw/openclaw.json
cp ~/.claude/settings.json.tokenpilot.bak ~/.claude/settings.json
# etc.

Next

• Configuration — tune TokenPilot settings
• Quick Start — start using TokenPilot