### Quick Start Setup Source: https://github.com/zjunlp/lightmem2/blob/main/CONTRIBUTING.md Quick start commands to clone the repository, enable Corepack, install dependencies, build, and run type checking. ```bash git clone https://github.com/zjunlp/LightRSI.git cd LightRSI corepack enable pnpm install pnpm build pnpm typecheck ``` -------------------------------- ### Run adapter doctor after install Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/codex/README.md Run the adapter doctor immediately after installation to verify the setup. Uses npm with the --prefix flag to target the components/adapters/codex directory. ```bash cd /path/to/LightRSI npm --prefix components/adapters/codex run doctor:codex ``` -------------------------------- ### Install from source checkout Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/codex/README.md Use the one-pass Cleaner installation flow from a source checkout. Requires corepack and pnpm. ```bash cd /path/to/LightRSI corepack pnpm cleaner:install:codex ``` -------------------------------- ### Install OpenClaw host integration Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/quick-start.md Builds and installs the shared lightrsi CLI, then installs the TokenPilot OpenClaw plugin. The first two commands are required because the OpenClaw plugin installer does not install the CLI. ```bash pnpm lightrsi:build pnpm lightrsi:install pnpm component:install:tokenpilot:openclaw ``` -------------------------------- ### Install from release archive Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/claude-code/README.md Run the bundled installer directly from a release archive. The archive is self-contained; keep the extracted directory in place after installation. ```bash node /path/to/package/dist/install-claude-code.js ``` -------------------------------- ### Verify Installation with lightrsi --help Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-lightrsi.md Displays the top-level command listing for the lightrsi CLI. Use this to verify the installation. ```bash lightrsi --help ``` -------------------------------- ### Start a Session: Codex Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/quick-start.md Start Codex normally and approve TokenPilot hooks if prompted. Open a new session so SessionStart can start the proxy. ```text Start Codex normally, approve TokenPilot hooks if prompted Open a new session so SessionStart can start the proxy ``` -------------------------------- ### Verify Installation with lightrsi context Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-lightrsi.md Shows your current default host, pinned session, and config target. Use this to verify the installation. ```bash lightrsi context ``` -------------------------------- ### Install TokenPilot OpenClaw adapter Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/openclaw/README.md Installs the TokenPilot runtime into ~/.openclaw/extensions/tokenpilot using OpenClaw's managed plugin installer, which records and consents the declared Context Engine capability. ```bash cd /path/to/LightRSI/components/adapters/openclaw npm run install:release ``` -------------------------------- ### Verify installation Source: https://github.com/zjunlp/lightmem2/blob/main/website/hosts/claude-code.md Verifies the installation. Expected output includes 'plugin entry enabled', 'config enabled', 'mode normal', 'stabilizer enabled', 'reduction enabled', and 'proxy healthy: yes'. ```bash lightrsi claude-code status lightrsi claude-code doctor ``` -------------------------------- ### Create install test fixtures for Codex proxy transactional install Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md Test fixture helpers for the transactional install behavior. `failingDaemonDependencies` simulates a daemon start failure. `createInstallFixture` creates a temporary install with a Codex config (default provider) and a TokenPilot config that is initially disabled. `createAlreadyInterceptedFixture` builds a fixture where the Codex config already points to a proxy base URL and the TokenPilot config is enabled with the corresponding upstream. These are used by `install.test.ts` tests to cover direct fallback and reinstall scenarios. ```ts function failingDaemonDependencies(): Partial { return { startDaemon: async () => { throw new Error("fixture_daemon_start_failed"); }, }; } ``` ```ts async function createInstallFixture(params: { provider: "openai" | "OPENAI"; }): Promise<{ root: string; codexConfigPath: string; tokenPilotConfigPath: string; hooksConfigPath: string; params: CodexInstallParams; }> { const root = await mkdtemp(join(tmpdir(), "lightrsi-codex-transaction-")); const codexConfigPath = join(root, "config.toml"); const tokenPilotConfigPath = join(root, "tokenpilot.json"); const hooksConfigPath = join(root, "hooks.json"); const providerSection = params.provider === "OPENAI" ? [ "", "[model_providers.OPENAI]", 'name = "OpenAI"', 'base_url = "https://api.openai.com/v1"', 'wire_api = "responses"', "requires_openai_auth = true", ] : []; await writeFile(codexConfigPath, [ `model_provider = ${JSON.stringify(params.provider)}`, ...providerSection, "", ].join("\n"), "utf8"); await writeTokenPilotCodexConfig(normalizeTokenPilotCodexConfig({ enabled: false, stateDir: join(root, "state"), proxyPort: await reserveUnusedPort(), }), tokenPilotConfigPath); return { root, codexConfigPath, tokenPilotConfigPath, hooksConfigPath, params: { codexConfigPath, tokenPilotConfigPath, hooksConfigPath, cliBinDir: join(root, "bin"), cliContextPath: join(root, ".lightrsi", "state", "cli-context.json"), probeMcp: false, }, }; } ``` ```ts async function createAlreadyInterceptedFixture(params: { proxyBaseUrl: string; upstreamBaseUrl: string; }) { const fixture = await createInstallFixture({ provider: "OPENAI" }); const proxyPort = Number(new URL(params.proxyBaseUrl).port); await writeFile(fixture.codexConfigPath, [ 'model_provider = "OPENAI"', "", "[model_providers.OPENAI]", 'name = "OpenAI"', `base_url = ${JSON.stringify(params.proxyBaseUrl)}`, 'wire_api = "responses"', "requires_openai_auth = true", "", ].join("\n"), "utf8"); await writeTokenPilotCodexConfig(normalizeTokenPilotCodexConfig({ enabled: true, stateDir: join(fixture.root, "state"), proxyPort, providerName: "OPENAI", upstreamProvider: "OPENAI", upstream: { name: "OpenAI", baseUrl: params.upstreamBaseUrl, wireApi: "responses", requiresOpenAIAuth: true, }, }), fixture.tokenPilotConfigPath); return fixture; } ``` -------------------------------- ### Install from source checkout Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/claude-code/README.md Use the one-pass Cleaner installation flow from a source checkout. The installer rejects missing or stale CLI, MCP, and adapter artifacts before modifying Claude Code configuration. ```bash cd /path/to/LightRSI corepack pnpm cleaner:install:claude-code ``` -------------------------------- ### Build and package the adapter Source: https://github.com/zjunlp/lightmem2/blob/main/website/hosts/deepseek-harness.md Run these commands from the LightRSI repository root to install dependencies, build the adapter, and create a tarball in the artifacts directory. ```bash corepack pnpm install corepack pnpm --filter @lightrsi/deepseek-harness-adapter build corepack pnpm --filter @lightrsi/deepseek-harness-adapter pack --pack-destination ./artifacts ``` -------------------------------- ### Run adapter doctor after install Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/claude-code/README.md Run the adapter doctor immediately after installing the Claude Code adapter. Use this to confirm the adapter is set up correctly before starting a real session. ```bash cd /path/to/LightRSI npm --prefix components/adapters/claude-code run doctor:claude-code ``` -------------------------------- ### Build and Install the LightRSI CLI Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-lightrsi.md Builds the shared lightrsi CLI and installs it to ~/.local/bin/lightrsi on Linux/macOS. On Windows, it creates a lightrsi.cmd launcher. For the complete Codex or Claude Code Cleaner flow, use pnpm cleaner:install:codex or pnpm cleaner:install:claude-code. ```bash pnpm lightrsi:build pnpm lightrsi:install ``` -------------------------------- ### Run installer tests Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md Runs the repository-level installer test suite; expects all installer planning and stale-artifact checks to pass. ```powershell node --test scripts/tests/install-cleaner.test.mjs ``` -------------------------------- ### Clone and prepare the LightRSI repository Source: https://github.com/zjunlp/lightmem2/blob/main/README.md Clones the LightRSI repository, enables Corepack, and installs dependencies with pnpm. Run once before installing any host-specific cleaner. ```bash git clone https://github.com/zjunlp/LightRSI.git cd LightRSI corepack enable pnpm install ``` -------------------------------- ### Example runtime model prefix Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/openclaw/README.md Example of the runtime model prefix. ```text lightrsi/gpt-5.4-mini ``` -------------------------------- ### Install TokenPilot for Claude Code Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-first-plugin.md Installs the TokenPilot plugin for Claude Code. Updates ~/.claude/settings.json, writes ~/.claude/tokenpilot.json, registers the shared MCP server, installs a SessionStart hook, and backs up existing Claude files as .tokenpilot.bak. ```bash corepack pnpm cleaner:install:claude-code ``` -------------------------------- ### Verify DeepSeek Harness installation Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-first-plugin.md Opens a session with the configured profile and runs /tokenpilot-status to verify installation. Reports estimator, scheduling, application, and deferral state without creating a model turn. ```text /tokenpilot-status ``` -------------------------------- ### Install TokenPilot for Codex with custom paths Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-first-plugin.md Sets custom paths for Codex config, hooks, and tokenpilot config before running the install command. ```bash 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" corepack pnpm cleaner:install:codex ``` -------------------------------- ### Run installer test and verify RED Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-raw-tty.md Runs the installer test. Expected: FAIL because the alias installer and fixedArgs option do not exist. ```powershell pnpm --filter @lightrsi/codex-adapter exec node --import tsx --test tests/cli-bin-install.test.ts ``` -------------------------------- ### Start a Session: OpenClaw Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/quick-start.md Use a lightrsi/ model like lightrsi/gpt-5.4-mini and run /lightrsi status. ```text Use a lightrsi/ model like lightrsi/gpt-5.4-mini Run: /lightrsi status ``` -------------------------------- ### Documentation site commands (pnpm --dir website) Source: https://github.com/zjunlp/lightmem2/blob/main/website/development/local-development.md Commands to start the dev server, build for production, and preview the production build of the documentation site. ```bash # Start dev server pnpm --dir website docs:dev # Build for production pnpm --dir website docs:build # Preview production build pnpm --dir website docs:preview ``` -------------------------------- ### Run isolated prerequisite check Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-raw-tty.md Runs the isolated start script with -CheckOnly. Expected output ISOLATED_TEST_PREREQUISITES=PASS. Must not install, start a daemon, prompt for a key, or change the work config. ```powershell & '.\var\codex-cleaner-isolated-test\start.ps1' -CheckOnly ``` -------------------------------- ### Clone, install, and build the LightRSI repository Source: https://github.com/zjunlp/lightmem2/blob/main/website/development/local-development.md Clones the repository, enables Corepack, installs dependencies, and builds all packages. Requires Node.js ≥ 18, pnpm ≥ 9, and Git. ```bash git clone https://github.com/zjunlp/LightRSI.git cd LightRSI corepack enable pnpm install pnpm build ``` -------------------------------- ### Install TokenPilot for OpenClaw with custom paths Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-first-plugin.md Sets custom paths for OpenClaw home and config before running the install command. Use when the default paths are not applicable. ```bash export LIGHTRSI_OPENCLAW_HOME="/path/to/openclaw-home" export OPENCLAW_CONFIG_PATH="/path/to/openclaw.json" pnpm component:install:tokenpilot:openclaw ``` -------------------------------- ### Run focused install tests (Task 4 Step 2) Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-elicitation.md Runs the focused install tests for the Codex adapter, expecting failure because the Cleaner server spec and artifact are absent. ```powershell pnpm --filter @lightrsi/codex-adapter test -- install.test.ts ``` -------------------------------- ### Inspect adapter state and configuration Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/codex/README.md Run these commands to inspect the adapter's state and configuration. Check the log file first if the local proxy is lost. Verify the expected install shape by checking the model provider, base URL, and MCP server configurations. ```bash cat ~/.codex/tokenpilot.json cat ~/.codex/hooks.json rg "model_provider|base_url" ~/.codex/config.toml rg "mcp_servers.tokenpilot_memory_fault_recover" ~/.codex/config.toml rg "mcp_servers.lightrsi_cleaner" ~/.codex/config.toml npm --prefix components/adapters/codex run doctor:codex tokenpilot-codex status ``` -------------------------------- ### Commit installer changes with descriptive message Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md Stages the installer script, tests, and README, then commits with a message about enforcing a healthy proxy after installation. ```powershell git add components/adapters/codex/scripts/install-codex.ts components/adapters/codex/tests/install-script.test.ts components/adapters/codex/tests/e2e.test.ts components/adapters/codex/README.md git commit -m "test(codex): enforce healthy proxy after installation" ``` -------------------------------- ### Install TokenPilot on OpenClaw, Codex, Claude Code, and DeepSeek Harness Source: https://github.com/zjunlp/lightmem2/blob/main/website/plugin-catalog/tokenpilot/installation.md Install TokenPilot on each host. OpenClaw, Codex, and Claude Code use their host adapter installers; DeepSeek Harness uses the Harness profile plugin installer and requires building and packing the adapter from the LightRSI repository first. ```bash pnpm component:install:tokenpilot:openclaw ``` ```bash corepack pnpm cleaner:install:codex ``` ```bash corepack pnpm cleaner:install:claude-code ``` ```bash # 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-.tgz ``` -------------------------------- ### Run adapter doctor Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/openclaw/README.md Runs the adapter doctor after installation to verify the OpenClaw adapter setup. ```bash cd /path/to/LightRSI/components/adapters/openclaw npm run doctor:openclaw ``` -------------------------------- ### Recommended first-run order for Codex Source: https://github.com/zjunlp/lightmem2/blob/main/components/presets/tokenpilot/README.md Commands to run in order for first-time Codex setup. ```text 1. `npm --prefix components/adapters/codex run install:codex` 2. trust hooks in Codex if prompted 3. open a new Codex session 4. `lightrsi codex doctor` 5. `lightrsi codex status` 6. after a few turns, `lightrsi codex report` ``` -------------------------------- ### Install and typecheck with corepack pnpm Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/deepseek-harness/README.md PowerShell commands to install dependencies and run typecheck for the adapter. ```powershell corepack pnpm install --frozen-lockfile corepack pnpm --dir .\components\adapters\deepseek-harness typecheck corepack pnpm --dir .\components\adapters\deepseek-harness test ``` -------------------------------- ### Start a Session: Claude Code Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/quick-start.md Start Claude Code normally and open a new session so SessionStart can start the gateway. ```text Start Claude Code normally Open a new session so SessionStart can start the gateway ``` -------------------------------- ### buildDirectCodexProviderConfig for transactional proxy install Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md Builds the direct Codex provider configuration that is used as the failure-safe routing value when the daemon cannot start. For built-in OpenAI, removes the openai and legacy proxy sections and sets openai_base_url; otherwise rewrites the provider section for proxying. ```ts function buildDirectCodexProviderConfig(params: { existing: string; providerName: string; builtInOpenAI: boolean; upstream: CodexProviderConfig; }): string { let next = replaceOrInsertRootAssignment( params.existing, "model_provider", quoteToml(params.providerName), ); if (params.builtInOpenAI) { next = removeProviderSectionFamily(next, "openai"); next = removeProviderSectionFamily(next, LEGACY_OPENAI_PROXY_PROVIDER); return replaceOrInsertRootAssignment( next, "openai_base_url", quoteToml(params.upstream.baseUrl), ); } return rewriteProviderSectionForProxy(next, { providerName: params.providerName, baseUrl: params.upstream.baseUrl, displayName: params.upstream.name ?? params.providerName, wireApi: params.upstream.wireApi, requiresOpenAIAuth: params.upstream.requiresOpenAIAuth, }); } ``` -------------------------------- ### Build commands Source: https://github.com/zjunlp/lightmem2/blob/main/website/development/build-and-test.md Commands to build the entire project, the CLI specifically, and individual adapters. Use `pnpm build` for everything, `pnpm lightrsi:build` and `pnpm lightrsi:install` for the CLI, and the `npm --prefix` commands for specific adapters. ```bash pnpm build pnpm lightrsi:build pnpm lightrsi:install npm --prefix components/adapters/openclaw run build npm --prefix components/adapters/codex run build npm --prefix components/adapters/claude-code run build ``` -------------------------------- ### Install TokenPilot for OpenClaw Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-first-plugin.md Installs the TokenPilot plugin for OpenClaw. Updates ~/.openclaw/openclaw.json, enables the plugin, switches plugins.slots.contextEngine to layered-context, sets default normal mode, and attempts to restart the OpenClaw gateway. ```bash pnpm component:install:tokenpilot:openclaw ``` -------------------------------- ### Run build, install, doctor, and package tests (Task 4 Step 6) Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-elicitation.md Builds the MCP and Codex adapter packages, then runs tests and typechecking. Expected: both MCP services build, install idempotently, and report independent health. ```powershell pnpm --filter @lightrsi/mcp build pnpm --filter @lightrsi/codex-adapter build pnpm --filter @lightrsi/codex-adapter test pnpm --filter @lightrsi/codex-adapter typecheck ``` -------------------------------- ### Install alias with fixed arguments Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-raw-tty.md Installs a Windows alias for 'lightrsi-clean' with fixed arguments. Used in failing launcher-content tests. ```typescript const alias = await installLightRsiCommandAlias({ adapterRoot, binDir, binName: "lightrsi-clean", fixedArgs: ["codex", "clean", "--require-tty"], platform: "win32", nodePath: "C:\\Program Files\\nodejs\\node.exe", }); ``` -------------------------------- ### Install TokenPilot for Codex Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-first-plugin.md Installs the TokenPilot plugin for Codex. Reroutes the active Codex provider through the local TokenPilot proxy, writes ~/.codex/tokenpilot.json, registers hooks, registers the shared tokenpilot_memory_fault_recover MCP server, and builds/installs the lightrsi CLI and skills. ```bash corepack pnpm cleaner:install:codex ``` -------------------------------- ### Install Cleaner for OpenClaw Source: https://github.com/zjunlp/lightmem2/blob/main/website/user-guide/context-cleaner.md Install the shared CLI and native OpenClaw plugin. Requires a Bash environment and `~/.local/bin` (or `LIGHTRSI_BIN_DIR`) on PATH. ```bash # Shared CLI, if you want to use the terminal commands pnpm lightrsi:build pnpm lightrsi:install # Native OpenClaw plugin pnpm component:install:tokenpilot:openclaw ``` -------------------------------- ### Install TokenPilot for Claude Code with custom paths Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-first-plugin.md Sets custom paths for Claude Code settings, MCP config, and tokenpilot config before running the install command. ```bash 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" corepack pnpm cleaner:install:claude-code ``` -------------------------------- ### Run Codex and Claude Adapter Install Tests Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-raw-tty.md Run the install tests for both adapters to verify the Codex assertions fail (RED) and Claude isolation passes. ```powershell pnpm --filter @lightrsi/codex-adapter exec node --import tsx --test tests/install.test.ts pnpm --filter @lightrsi/claude-code-adapter exec node --import tsx --test tests/install.test.ts ``` -------------------------------- ### Install DeepSeek Harness host integration Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/quick-start.md Builds and packs the DeepSeek Harness adapter, then installs it as a Cordis plugin into the selected profile. Requires a working Harness checkout and Node.js matching the adapter requirements. The plugin is disabled by default; you must supply a persistent stateDir and estimator/eviction settings and enable it. ```bash # 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-.tgz ``` -------------------------------- ### Enable Corepack and Install Dependencies Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-lightrsi.md Enables Corepack and installs all workspace dependencies across the plugin packages and host adapters. Requires pnpm version 9 or higher. ```bash corepack enable pnpm install ``` -------------------------------- ### Install DeepSeek Harness adapter plugin Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-first-plugin.md Installs the generated archive into a DeepSeek Harness profile. Replace the archive path and profile as needed. The plugin is registered as tokenpilot-dsh and remains disabled until configured. ```bash node --import tsx/esm apps/cli/src/bin.ts plugin --profile web add /absolute/path/to/lightrsi-deepseek-harness-adapter-.tgz ``` -------------------------------- ### Run focused tests for failed install Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md Runs the two focused tests from Step 2. Expected to fail because installCodexTokenPilot does not accept lifecycle dependencies and writes loopback before daemon startup. ```powershell npm --prefix components/adapters/codex test -- --test-name-pattern="failed built-in OpenAI|failed reinstall" ``` -------------------------------- ### Start a Session: DeepSeek Harness Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/quick-start.md Load the profile containing the configured and enabled tokenpilot-dsh plugin, open a Harness session, and run /tokenpilot-status. ```text Load the profile containing the configured and enabled tokenpilot-dsh plugin Open a Harness session Run: /tokenpilot-status ``` -------------------------------- ### MCP configuration for lightrsi_cleaner server Source: https://github.com/zjunlp/lightmem2/blob/main/docs/design/codex-cleaner-elicitation.md Installer writes two independent MCP blocks: the existing recovery MCP and the new lightrsi_cleaner server. The cleaner server uses the node command, points to the cleaner-mcp-server.js adapter, sets a 90-second startup timeout, and configures TOKENPILOT_STATE_DIR. ```toml [mcp_servers.tokenpilot_memory_fault_recover] # Existing recovery MCP configuration [mcp_servers.lightrsi_cleaner] command = "" args = ["/dist/cleaner-mcp-server.js"] startup_timeout_sec = 90 [mcp_servers.lightrsi_cleaner.env] TOKENPILOT_STATE_DIR = "" ``` -------------------------------- ### Verify It Works: OpenClaw Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/quick-start.md Run /lightrsi doctor or lightrsi openclaw doctor to verify the installation. ```bash /lightrsi doctor # Or outside OpenClaw: lightrsi openclaw doctor ``` -------------------------------- ### Verify installation per host Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-first-plugin.md Runs per-host doctor and clean help commands for OpenClaw, Codex, and Claude Code to verify installation. ```bash lightrsi openclaw doctor lightrsi codex doctor lightrsi claude-code doctor lightrsi codex clean --help lightrsi claude-code clean --help ``` -------------------------------- ### Install, test proxy, and stop daemon in E2E Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md E2E test fragment that installs the proxy, verifies the daemon is running, sends a POST /responses request, and stops the daemon via stopDaemon in a finally-like cleanup. ```ts const result = await installCodexTokenPilot({ codexConfigPath, hooksConfigPath, tokenPilotConfigPath, }); assert.equal(result.daemon.running, true); const response = await fetch(`${result.baseUrl}/responses`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(requestPayload), }); assert.equal(response.status, 200); const installedConfig = await loadTokenPilotCodexConfig(tokenPilotConfigPath); await stopDaemon(installedConfig); ``` -------------------------------- ### Recommended first-run order for Claude Code Source: https://github.com/zjunlp/lightmem2/blob/main/components/presets/tokenpilot/README.md Commands to run in order for first-time Claude Code setup. ```text 1. `npm --prefix components/adapters/claude-code run install:claude-code` 2. open a new Claude Code session 3. `lightrsi claude-code doctor` 4. `lightrsi claude-code status` 5. after a few turns, `lightrsi claude-code report` ``` -------------------------------- ### Smoke test verification steps for isolated install Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md Ordered verification steps for an isolated install smoke test on a temporary HOME/USERPROFILE and loopback port. ```text installer exits 0 tokenpilot.json contains the selected port and real upstream GET /health returns 200 and adapter=tokenpilot-codex config.toml points to exactly that selected port tokenpilot-codex.pid names a live process stopDaemon removes the process and PID file ``` -------------------------------- ### LightRSI development workflow commands (pnpm) Source: https://github.com/zjunlp/lightmem2/blob/main/website/development/local-development.md Commands for building all packages, typechecking, building the CLI, installing the CLI locally, and running tests. ```bash # Build all packages pnpm build # Typecheck pnpm typecheck # Build the CLI pnpm lightrsi:build # Install the CLI locally pnpm lightrsi:install # Run tests pnpm lightrsi:test ``` -------------------------------- ### Documentation commands Source: https://github.com/zjunlp/lightmem2/blob/main/website/development/build-and-test.md Commands for documentation development: `docs:dev` starts a dev server with hot reload, `docs:build` creates a production build, and `docs:preview` previews the production build. ```bash pnpm --dir website docs:dev pnpm --dir website docs:build pnpm --dir website docs:preview ``` -------------------------------- ### Expected OpenClaw config after TokenPilot install Source: https://github.com/zjunlp/lightmem2/blob/main/website/hosts/openclaw.md Expected TokenPilot section in ~/.openclaw/openclaw.json after installation, showing the layered-context engine and enabled plugin with normal mode. ```json { "plugins": { "slots": { "contextEngine": "layered-context" }, "entries": { "tokenpilot": { "enabled": true, "mode": "normal" } } } } ``` -------------------------------- ### Wrapper executable for lightrsi-clean Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/specs/2026-09-13-codex-cleaner-raw-tty-design.md Shows the installed executable wrapper for the lightrsi-clean command. ```text lightrsi codex clean ``` -------------------------------- ### Run Codex and Claude install tests (Task 5 Step 2) Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-elicitation.md Runs the Codex and Claude Code install tests to confirm the Codex assertion fails while the Claude test still passes. ```powershell pnpm --filter @lightrsi/codex-adapter test -- install.test.ts pnpm --filter @lightrsi/claude-code-adapter test -- install.test.ts ``` -------------------------------- ### Install Codex Token Pilot and format proxy daemon status Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md TypeScript entry point for the Codex installer that calls installCodexTokenPilot with environment-driven config paths)Skip the manual daemon status check. ```ts export function formatProxyInstallStatus( daemon: CodexInstallResult["daemon"], ): string[] { return [ `Proxy daemon: ${daemon.running ? "running" : "not running"}`, `Proxy health: ${daemon.running ? "ok" : "failed"}`, `Proxy log: ${daemon.logPath}`, "SessionStart hooks remain installed as an idempotent recovery path.", ]; } async function main(): Promise { const result = await installCodexTokenPilot({ codexConfigPath: process.env.CODEX_CONFIG_PATH, tokenPilotConfigPath: process.env.TOKENPILOT_CODEX_CONFIG, hooksConfigPath: process.env.CODEX_HOOKS_CONFIG_PATH, }); // Keep the existing summary lines, then: for (const line of formatProxyInstallStatus(result.daemon)) console.log(line); } if (/install-codex\.(?:js|ts)$/u.test(process.argv[1] ?? "")) { main().catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); }); } ``` -------------------------------- ### Preferred package structure for host adapters Source: https://github.com/zjunlp/lightmem2/blob/main/docs/adapter-playbook.md Shows the directory layout for placing adapter code. Shared logic goes in `packages/foundation/*` or `packages/features/*`, while host-specific config, transcript parsing, command wiring, and install logic belong in the host adapter directory. ```text components/ ├── packages/ │ ├── foundation/ │ └── features/ ├── presets/ ├── products/ └── adapters// ``` -------------------------------- ### Clone the LightRSI Repository Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-lightrsi.md Clones the LightRSI repository and changes into the project directory. This is the first step of the installation process. ```bash git clone https://github.com/zjunlp/LightRSI.git cd LightRSI ``` -------------------------------- ### Run Context Cleaner Source: https://github.com/zjunlp/lightmem2/blob/main/website/hosts/claude-code.md Runs the Context Cleaner interactively. Use the installed lightrsi-clean skill for analysis only; the skill must not choose or approve tasks for you. ```bash lightrsi claude-code clean ``` -------------------------------- ### Commit isolated primitives Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md Commits the isolated primitives for transactional proxy installation. This commit prepares the codebase before the daemon start and health-gate implementation. ```powershell git add components/adapters/codex/src/install.ts components/adapters/codex/tests/install.test.ts git commit -m "refactor(codex): prepare transactional proxy installation" ``` -------------------------------- ### Test failed install preserves direct route Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md Two tests verify that a failed daemon start during install preserves the direct OpenAI route or replaces an old loopback route with the persisted upstream. They inject failing lifecycle dependencies and assert the resulting config does not contain a loopback address. ```typescript test("failed built-in OpenAI proxy start preserves a direct OpenAI route", async () => { const fixture = await createInstallFixture({ provider: "openai" }); await assert.rejects( installCodexTokenPilot(fixture.params, { startDaemon: async () => { throw new Error("fixture_daemon_start_failed"); }, stopDaemon: async (config) => ({ ...(await readDaemonStatus(config)), stopped: false, }), }), /fixture_daemon_start_failed/, ); const text = await readFile(fixture.codexConfigPath, "utf8"); assert.match(text, /model_provider = "openai"/); assert.match(text, /openai_base_url = "https:\/\/api\.openai\.com\/v1"/); assert.doesNotMatch(text, /127\.0\.0\.1/); }); test("failed reinstall replaces an old loopback route with the persisted upstream", async () => { const fixture = await createAlreadyInterceptedFixture({ proxyBaseUrl: "http://127.0.0.1:17667/v1", upstreamBaseUrl: "https://provider.example/v1", }); await assert.rejects( installCodexTokenPilot(fixture.params, failingDaemonDependencies()), /fixture_daemon_start_failed/, ); const text = await readFile(fixture.codexConfigPath, "utf8"); assert.match(text, /base_url = "https:\/\/provider\.example\/v1"/); assert.doesNotMatch(text, /127\.0\.0\.1/); }); ``` -------------------------------- ### Export installLightRsiCommandAlias Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-raw-tty.md Exports the reusable alias installer function signature. The extensionless wrapper uses 'exec'; on Windows, call the shared launcher writer with fixedArgs. ```typescript export async function installLightRsiCommandAlias(params: { adapterRoot: string; binDir: string; binName: string; fixedArgs: readonly string[]; platform?: NodeJS.Platform; nodePath?: string; }): Promise<{ binPath: string; launcherPath?: string; cliDistPath: string; }>; ``` -------------------------------- ### Commit the launcher primitive Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-raw-tty.md Stages and commits the modified launcher and installer files. ```powershell git add -- components/adapters/shared/windows-command-launcher.ts components/adapters/shared/cli-bin-install.ts components/adapters/codex/tests/cli-bin-install.test.ts git commit -m "feat(codex): add Cleaner command launcher" ``` -------------------------------- ### Expected output from isolated start script Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-raw-tty.md Expected output after isolated installation, requiring temporary alias files. Sets the isolated test root environment variable before launching Codex. ```text RAW_TTY_COMMAND=!lightrsi-clean WORK_CONFIG_UNCHANGED=TRUE ISOLATED_TEST_ENV=READY ``` -------------------------------- ### Build CLI and adapters in native WSL Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-02-monotonic-timeout-reliability.md Builds the CLI and both adapters in the native WSL environment before running tests. ```bash corepack pnpm --dir components/products/cli build corepack pnpm --dir components/adapters/codex build corepack pnpm --dir components/adapters/claude-code build ``` -------------------------------- ### Codex CLI: Verify adapter with lightrsi codex commands Source: https://github.com/zjunlp/lightmem2/blob/main/README.md Verify the Codex adapter after installing and trusting the TokenPilot hooks. Expected first-run shape: doctor reports proxy healthy: yes, status shows stabilizer and reduction enabled, and report no longer says 'No TokenPilot session stats yet.' after a few turns. ```bash lightrsi codex status lightrsi codex doctor lightrsi codex report lightrsi codex mode normal lightrsi codex reduction status lightrsi codex stabilizer target user ``` -------------------------------- ### Build, typecheck, and test the LightRSI CLI Source: https://github.com/zjunlp/lightmem2/blob/main/components/products/cli/README.md Run these pnpm commands from the repository root to build, typecheck, and test the `components/products/cli` package. Use when developing or verifying the CLI product. ```bash pnpm --dir components/products/cli build pnpm --dir components/products/cli typecheck pnpm --dir components/products/cli test ``` -------------------------------- ### Build and typecheck the openclaw adapter Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/openclaw/README.md Build and type-check the openclaw adapter. Run from the adapter directory. ```bash cd /path/to/LightRSI/components/adapters/openclaw corepack pnpm build corepack pnpm typecheck ``` -------------------------------- ### Basic LightRSI CLI commands Source: https://github.com/zjunlp/lightmem2/blob/main/README.md Basic standalone CLI commands for LightRSI. Use these first, then the session-aware and advanced ones when needed. `lightrsi report` shows the latest available report across hosts, `lightrsi visual` opens the shared browser visual, `lightrsi use ` sets the default host, `lightrsi use session ` pins the default session, `lightrsi context` shows current defaults, and `lightrsi session report` reads a specific session directly. ```bash lightrsi report lightrsi visual lightrsi use openclaw lightrsi use codex session lightrsi context lightrsi session report ``` -------------------------------- ### Verify via shared CLI (lightrsi codex) Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/codex/README.md Check adapter status, run diagnostics, generate reports, set mode to normal, and view reduction status. Expected first-run output: doctor reports 'proxy healthy: yes', status shows stabilizer and reduction enabled, and report no longer says 'No TokenPilot session stats yet.' ```bash lightrsi codex status lightrsi codex doctor lightrsi codex report lightrsi codex mode normal lightrsi codex reduction status ``` -------------------------------- ### Assert Cleaner CLI Paths in Codex Install Test Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-raw-tty.md In the temp-directory Codex install test, assert that `cleanCliBinPath` points to the extensionless alias and `cleanCliLauncherPath` points to the `.cmd` launcher on Windows only. ```ts assert.equal(result.cleanCliBinPath, join(cliBinDir, "lightrsi-clean")); assert.equal( result.cleanCliLauncherPath, process.platform === "win32" ? join(cliBinDir, "lightrsi-clean.cmd") : undefined, ); ``` -------------------------------- ### Provider-mode with web-search scenario (opt-in) Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/codex/README.md Extends the real-provider item matrix with a hosted web-search replay. Additional scenarios are observational by default; add --strict-compatibility-scenarios to make them hard gates. If the provider omits the item or the probe fails, the sanitized v3 artifact is still written with 'status: not-observed' and a categorical 'reason'. ```bash npm --prefix components/adapters/codex run smoke:context-rebase:codex -- \ --mode=provider \ --compatibility-scenarios=web-search \ --output-dir=/path/to/sanitized-evidence ``` -------------------------------- ### Analyze session with /tokenpilot-clean Source: https://github.com/zjunlp/lightmem2/blob/main/website/hosts/deepseek-harness.md Run this command after finishing a task and sending an ordinary request so the estimator records its completed state. It returns a text plan with selectable tasks marked [ ] and protected tasks marked [-], using chars_only accounting. Requires the host's commands service. ```text /tokenpilot-clean ``` -------------------------------- ### Verify installation with lightrsi doctor Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-first-plugin.md Runs the shared doctor command for OpenClaw, Codex, and Claude Code to verify installation. Look for 'plugin entry enabled', 'config enabled', and 'proxy healthy: yes'. ```bash lightrsi doctor ``` -------------------------------- ### Test daemon starts before committing loopback Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md Adds a test that verifies the daemon starts before loopback routing is committed, checking that the config file still contains the remote endpoint during startup and loopback only after completion. ```ts test("install starts a healthy daemon before committing loopback routing", async () => { const fixture = await createInstallFixture({ provider: "OPENAI" }); let configObservedDuringStart = ""; const result = await installCodexTokenPilot(fixture.params, { startDaemon: async (config) => { configObservedDuringStart = await readFile(fixture.codexConfigPath, "utf8"); return { running: true, started: true, pid: 4242, ...daemonPaths(config), }; }, stopDaemon: async (config) => ({ running: false, stopped: false, ...daemonPaths(config), }), }); assert.match(configObservedDuringStart, /https:\/\/api\.openai\.com\/v1/); assert.doesNotMatch(configObservedDuringStart, /127\.0\.0\.1/); assert.equal(result.daemon.running, true); assert.match(await readFile(fixture.codexConfigPath, "utf8"), /127\.0\.0\.1/); }); ``` -------------------------------- ### Per-package build and typecheck commands (npm --prefix) Source: https://github.com/zjunlp/lightmem2/blob/main/website/development/local-development.md Commands to build a specific adapter package and typecheck a specific runtime-core package using npm with the --prefix flag. ```bash # Build a specific adapter npm --prefix components/adapters/openclaw run build # Typecheck a specific package npm --prefix components/packages/foundation/runtime-core run typecheck ``` -------------------------------- ### Legacy state directory Source: https://github.com/zjunlp/lightmem2/blob/main/components/adapters/openclaw/README.md Legacy state directory for older installs. ```text $HOME/.openclaw/tokenpilot-plugin-state/tokenpilot/ ``` -------------------------------- ### Build and package DeepSeek Harness adapter Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/install-first-plugin.md Builds and packages the DeepSeek Harness adapter from the LightRSI repository. Produces an archive in ./artifacts. ```bash corepack pnpm --filter @lightrsi/deepseek-harness-adapter build corepack pnpm --filter @lightrsi/deepseek-harness-adapter pack --pack-destination ./artifacts ``` -------------------------------- ### Restore OpenClaw config from backup Source: https://github.com/zjunlp/lightmem2/blob/main/website/hosts/openclaw.md Restores the OpenClaw configuration from the backup created during installation. ```bash cp ~/.openclaw/openclaw.json.tokenpilot.bak ~/.openclaw/openclaw.json ``` -------------------------------- ### Invoke lightrsi-clean command Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/specs/2026-09-13-codex-cleaner-raw-tty-design.md Invokes the documented Codex command to start the Cleaner flow. ```text !lightrsi-clean ``` -------------------------------- ### Run both adapter suites (Task 5 Step 4) Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-13-codex-cleaner-elicitation.md Runs both adapter test suites after splitting Cleaner analysis instructions by bridge style. Expected: Codex uses MCP and Claude retains the existing behavior. ```powershell pnpm --filter @lightrsi/codex-adapter test pnpm --filter @lightrsi/claude-code-adapter test ``` -------------------------------- ### lightrsi clean --plan --select follow-up command Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/specs/2026-09-01-codex-claude-cli-cleaner-design.md Exact follow-up command printed by the non-TTY clean plan. Use --plan and --select to explicitly approve the plan and select tasks; this is not a default behavior. ```bash lightrsi clean --plan --select ``` -------------------------------- ### TokenPilot Pipeline Diagram Source: https://github.com/zjunlp/lightmem2/blob/main/website/plugin-catalog/tokenpilot/overview.md ASCII diagram of the TokenPilot pipeline, showing the three techniques: Stable Prefix, Context Reduction, and Context Eviction, with their effects on cache hit rate, context size, and session growth. ```text ┌─────────────────────────────────────────────────────┐ │ TokenPilot Pipeline │ ├─────────────────────────────────────────────────────┤ │ 1. Stable Prefix │ │ Rewrites context into cache-stable form │ │ → Higher cache hit rate │ ├─────────────────────────────────────────────────────┤ │ 2. Context Reduction │ │ Trims oversized tool output before it pollutes │ │ → Leaner context per turn │ ├─────────────────────────────────────────────────────┤ │ 3. Context Eviction │ │ Limits how much old context is carried forward │ │ → Sessions don't grow unbounded │ └─────────────────────────────────────────────────────┘ ``` -------------------------------- ### Run the report command Source: https://github.com/zjunlp/lightmem2/blob/main/website/plugin-catalog/tokenpilot/reports-and-visuals.md Shows a summary of token usage, cache efficiency, and cost savings for the current session. Use the standalone form or specify a host (openclaw, codex, claude-code). Inside OpenClaw, use the slash command. ```bash # Standalone CLI lightrsi report # Per-host lightrsi openclaw report lightrsi codex report lightrsi claude-code report # Inside OpenClaw /lightrsi report ``` -------------------------------- ### Add daemon field to result type Source: https://github.com/zjunlp/lightmem2/blob/main/docs/superpowers/plans/2026-09-20-codex-proxy-transactional-install.md Adds a daemon field to the CodexInstallResult type, combining DaemonStatus with a started boolean. ```typescript daemon: DaemonStatus & { started: boolean }; ``` -------------------------------- ### Enable TokenPilot plugin for Codex Source: https://github.com/zjunlp/lightmem2/blob/main/website/user-guide/enabling-disabling.md Enables the TokenPilot plugin for the Codex host. The plugin starts processing on the next turn. ```bash lightrsi codex plugin tokenpilot enable ``` -------------------------------- ### OpenClaw: Full runtime summary commands Source: https://github.com/zjunlp/lightmem2/blob/main/README.md Run these OpenClaw commands for a fuller runtime summary. /lightrsi doctor is the quickest integration self-check, /lightrsi visual opens the local visual inspector, and /lightrsi mode switches preset runtime behavior (conservative, normal, or aggressive). ```text /lightrsi report /lightrsi doctor /lightrsi visual /lightrsi mode normal ``` -------------------------------- ### Enable TokenPilot plugin for OpenClaw Source: https://github.com/zjunlp/lightmem2/blob/main/website/user-guide/enabling-disabling.md Enables the TokenPilot plugin for the OpenClaw host. The plugin starts processing on the next turn. ```bash lightrsi openclaw plugin tokenpilot enable ```