# pi-rlm-runtime

A recursive language-model runtime for [Pi](https://github.com/earendil-works/pi), based on the architecture behind [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent).

pi-rlm-runtime lets Pi work beyond a single conversation context. It can retain a large working set, delegate independent work to nested sub-agents, and bring the useful results back into the main conversation.

## Install

Requires Node.js 22.19 or newer, Pi 0.84.x, and [`uv`](https://docs.astral.sh/uv/).

```bash
pi install npm:pi-rlm-runtime
```

## Run Pi with pi-rlm-runtime

```bash
pi --rlm-runtime
```

Then use Pi normally. Ask it to delegate when a task has independent parts:

```text
Review this codebase. Use sub-agents to inspect the architecture, runtime,
and tests in parallel, then reconcile their findings.
```

The runtime gives the agent a persistent working environment and the ability to create, message, inspect, and stop sub-agents. Each sub-agent has its own Pi conversation and state, shares the project directory, and inherits the parent model unless another is selected.

Sub-agents may create further sub-agents. Set the recursion limit when starting Pi:

```bash
pi --rlm-runtime --rlm-runtime-max-depth 6
```

The default depth is 4. The supported range is 0–16.

## View active sub-agents

Active sub-agents appear as a nested tree above the editor. Press `Ctrl+Alt+A` or run `/subagents` to expand or collapse it. Dormant sub-agents are hidden, and expanded trees are capped at 12 rows.

## Agent API

The runtime preloads two Python objects for the agent:

```python
models = await rlm.find_models("sonnet")
reviewer = await rlm(
    "Review the authorization flow and report concrete findings.",
    name="auth-reviewer",
    model=models[0].selector,
)

agents = await agent_message.list_agents()
await agent_message.send(
    "Check the regression tests next.",
    receiver_role="subagent",
    receiver_name=reviewer.name,
)

await rlm.delete_subagent(reviewer)
```

`rlm()` returns when the sub-agent starts. Messages and shared files carry results back without copying the sub-agent's full context into its parent. If a sub-agent exits without sending a message, its final response or error is forwarded automatically.

`rlm.find_models()` searches the authenticated models available to Pi. Its selectors are exact; requesting an unavailable model fails instead of choosing a fallback.

`agent_message.send()` accepts `parent`, `sibling`, or `subagent` as `receiver_role`. Messages to more distant agents are relayed through the tree.

## Python environment

The runtime uses a cached Python 3.11 environment managed by uv. To use another interpreter:

```bash
export PI_RLM_RUNTIME_PYTHON=/absolute/path/to/python
pi --rlm-runtime
```

The interpreter must provide IPython and ipykernel.

## Development

```bash
npm install
npm run check
```

## License

MIT