pi-rlm

pi-rlm

Recursive Language Model (RLM) extension for Pi coding agent.

This extension adds an rlm tool that performs depth-limited recursive decomposition:

• planner node decides solve vs decompose
• child nodes recurse on subtasks
• synthesizer node merges child outputs

It includes guardrails for depth, node budget, branching, and cycle detection.

Install

pi install /path/to/pi-rlm

Or as a package:

pi install npm:pi-rlm

CLI Wrapper

This package also ships a lightweight CLI wrapper:

pi-rlm --task "Analyze architecture of this repo" --mode auto --tools-profile read-only

Or with a positional task:

pi-rlm "Find top reliability risks in this codebase" --backend sdk --max-depth 3

Local shortcut from this repo:

npm run cli -- "Find top reliability risks in this codebase" --backend sdk --max-depth 3

JSON output:

pi-rlm "Summarize repo" --mode solve --json

Live tree visualization (TTY):

pi-rlm "Analyze architecture of this repo" --tools-profile read-only --live

Use current tmux session windows instead of a separate pi-rlm-<runId> session:

pi-rlm "Analyze architecture of this repo" --backend tmux --tmux-current-session

Notes:

• The wrapper runs a single synchronous op=start operation.
• It shells out to the installed pi CLI and loads this extension automatically.
• --live renders a real-time tree by reading events.jsonl while the run executes.
• CLI source is authored in TypeScript (src/cli.ts) and built with npm run build:cli (Node + tsc, no Bun runtime required).
• npm publish runs prepack, so the built CLI (bin/pi-rlm.mjs) is included in the published package.

Tool API

The extension registers one tool: rlm.

op=start (default)

rlm({
  task: "Implement auth refactor and validate tests",
  backend: "sdk",         // sdk | cli | tmux
  mode: "auto",           // auto | solve | decompose
  tmuxUseCurrentSession: false,
  maxDepth: 2,
  maxNodes: 24,
  maxBranching: 3,
  concurrency: 2,
  toolsProfile: "coding", // coding | read-only
  timeoutMs: 180000,
  async: false
})

op=status

rlm({ op: "status", id: "a1b2c3d4" })

If id is omitted, returns recent runs.

op=wait

rlm({ op: "wait", id: "a1b2c3d4", waitTimeoutMs: 120000 })

op=cancel

rlm({ op: "cancel", id: "a1b2c3d4" })

Backend Behavior

backend: "sdk" (default)

• Runs subcalls in-process via Pi SDK sessions
• No fresh pi CLI process per subcall
• Best default for low overhead and deterministic orchestration

backend: "cli"

• Runs each subcall as a fresh pi -p subprocess
• Good isolation, easier debugging in logs
• Slightly higher process overhead

backend: "tmux"

Default behavior:

• Creates one detached tmux session per RLM run (pi-rlm-<runId>)
• Uses depth-oriented windows (depth-0, depth-1, ...)
• Starts subcalls in panes within the matching depth window (tiled layout)

Optional behavior:

• Set tmuxUseCurrentSession: true (or CLI flag --tmux-current-session) to place panes in the current tmux session
• Uses windows named rlm-depth-0, rlm-depth-1, ... in that current session

General:

• Uses fresh pi process per subcall
• Useful when you specifically want tmux-level observability/control

Artifacts

Each run writes artifacts to:

/tmp/pi-rlm-runs/<runId>/
  events.jsonl
  tree.json
  output.md

Guardrails

• maxDepth: recursion depth cap
• maxNodes: total node budget
• maxBranching: child count cap per decomposition
• cycle detection by normalized task lineage
• cancellable runs (op=cancel)

Development

npm install
npm run typecheck