pi-recursive
The pure Pi extension that lets Pi recursively call
itself — a native rlm_query tool that delegates a bounded subtask to a child Pi agent with a
fresh context window, down to a configurable depth.
This is the canonical recursion machinery. The ypi CLI
wrapper is a convenience layer around this same extension (launcher defaults, a shell-compatible
rlm_query with pipes/async, cost/session helpers). If you just want recursion inside plain Pi,
install this.
Install
pi install npm:pi-recursive
# or try it for one session without installing:
pi -e npm:pi-recursive "Use rlm_query to ask a child what 2 + 2 is."What you get
- A native
rlm_queryPi tool — no shell helper, no launcher, nojjrequired. - Recursive children share the active provider/model, bounded by depth, call count, timeout, and budget guardrails.
jjworkspace isolation is used automatically when available; recursion still works without it.
The shell-compatible rlm_query command, async jobs, and CLI ergonomics live in the ypi
wrapper package and are opt-in via YPI_SHELL_HELPER=1.
Configuration
Behavior is controlled through RLM_* environment variables. The pure extension honors:
| Variable | Example | What it does |
|---|---|---|
RLM_MAX_DEPTH |
RLM_MAX_DEPTH=3 |
How deep recursion can go (default 3). |
RLM_CHILD_MODEL |
RLM_CHILD_MODEL=haiku |
Use a cheaper model for sub-calls at depth > 0. |
RLM_CHILD_PROVIDER |
RLM_CHILD_PROVIDER=anthropic |
Provider for sub-calls at depth > 0. |
RLM_BUDGET |
RLM_BUDGET=0.50 |
Max dollar spend for the recursive tree (requires RLM_JSON=1, the default). |
RLM_TIMEOUT |
RLM_TIMEOUT=60 |
Wall-clock limit (seconds) for the entire recursive tree. |
RLM_MAX_CALLS |
RLM_MAX_CALLS=20 |
Max total rlm_query invocations. |
RLM_JJ |
RLM_JJ=0 |
Disable jj workspace isolation (used automatically when available). |
The shell-helper guardrails and cost/session CLI commands (e.g. rlm_cost) documented in the
ypi README apply only to the ypi wrapper package, not
to this pure extension.
Compatibility
This extension is verified against @earendil-works/pi-coding-agent 0.79.4. The peer
dependency is declared as ^0.79.4, so forward patch/minor Pi releases are accepted; the
extension API surface used (ExtensionAPI/ExtensionContext/defineTool type imports) is stable
across patches.
Source
Developed in the rawwerks/ypi monorepo; pi-recursive is the
extension-only publish view of the same source.