LightRSI

https://github.com/zjunlp/lightmem2
Admin
LightRSI is a modular runtime for building, evaluating, and safely deploying recursive improvement...
Tokens:117,803
Snippets:1,118
Trust Score:10
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### 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<CodexInstallDependencies> {
  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 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
```

--------------------------------

### 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
```

--------------------------------

### 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
```

--------------------------------

### 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
```

--------------------------------

### 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
```

--------------------------------

### 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
```

--------------------------------

### 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
```

--------------------------------

### 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
```

--------------------------------

### 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"
```

--------------------------------

### 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
```

--------------------------------

### 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/);
});
```

--------------------------------

### Start a Session: OpenClaw

Source: https://github.com/zjunlp/lightmem2/blob/main/website/getting-started/quick-start.md

Use a lightrsi/<model> model like lightrsi/gpt-5.4-mini and run /lightrsi status.

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

--------------------------------

### 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 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
```

--------------------------------

### 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,
  });
}
```

--------------------------------

### 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
```

--------------------------------

### 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
```

--------------------------------

### 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
```

--------------------------------

### 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
```

--------------------------------

### 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
```

--------------------------------

### 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"
```

--------------------------------

### 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`
```

--------------------------------

### 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
```

--------------------------------

### 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 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-<version>.tgz
```
Tokens:
Raw