🔁 pi-recurse

Programmatic recursive subagent spawning for pi

LLM makes ONE tool call, extension code handles parallel spawning and result aggregation.

---

This project is the spiritual successor to ypi by @rawwerks, originally created as a bash wrapper around Pi that enabled recursive LLM calls with guardrails.

Why the conversion? The original ypi proved that recursive subagents could work effectively, but required the LLM to generate bash scripts for parallelization. By converting to a proper Pi extension, pi-recurse achieves:

• True programmatic looping — parallel execution happens in TypeScript code, not bash generated by the LLM
• Better integration — hot-reload with /reload, automatic tool discovery, native Pi packaging
• Structured results — full TypeScript types instead of bash string manipulation
• Single entry point — just pi, no wrapper scripts needed

Thank you to the original ypi for pioneering the concept of depth-limited recursive LLM calls in a coding agent context.

---

Installation

Via npm (Recommended)

pi install npm:pi-recurse

Local Development

git clone https://github.com/monotykamary/pi-recurse.git
cd pi-recurse
pi install .

The extension will be auto-discovered by Pi on next start, or use /reload to load it immediately.

---

Usage

The extension adds a recurse tool to Pi, enabling three execution modes:

Single Mode — One-off delegation

recurse({
  mode: 'single',
  prompt: 'Analyze the error handling in src/auth.ts',
  context: fileContent, // optional context to pipe
});

Parallel Mode — Batch processing

recurse({
  mode: 'parallel',
  tasks: [
    { id: 'auth', prompt: 'Review auth module' },
    { id: 'db', prompt: 'Review database layer' },
    { id: 'api', prompt: 'Review API routes' },
  ],
  concurrency: 3,
  timeoutPerTask: 120,
});

Key advantage: All 3 subagents spawn from a single LLM tool call. The extension handles Promise.all() style concurrency internally — no autoregressive steps between spawns.

Chain Mode — Sequential dependencies

recurse({
  mode: 'chain',
  chain: [
    { id: 'read', prompt: 'Read README.md and summarize' },
    { id: 'analyze', prompt: 'Given this summary: {previous} — identify risks' },
    { id: 'plan', prompt: 'Given these risks: {previous} — suggest mitigations' },
  ],
});

---

Guardrails

Environment variables control recursion limits across the entire call tree:

Variable	Default	Description
RLM_MAX_DEPTH	3	Maximum recursion depth (0 = root)
RLM_MAX_CALLS	100	Maximum total recurse invocations
RLM_TIMEOUT	600	Wall-clock seconds for entire tree
RLM_BUDGET	—	Max dollar spend (e.g., 0.50)
RLM_CHILD_MODEL	—	Model override for depth > 0
RLM_DISABLE_TOOL_AT	3	Disable recurse tool at this depth
RLM_TRACE_ID	auto	Links all sessions in recursive tree

At deep depths (≥ RLM_DISABLE_TOOL_AT), the recurse tool automatically disables itself and guides agents to work directly instead of delegating.

---

Architecture: From Bash to Extension

Original ypi (Bash Wrapper)

ypi "analyze this codebase"
    ↓
Launcher sets env, execs pi with custom system prompt
    ↓
LLM generates bash loop for parallel tasks:
    for f in $(find src -name "*.ts"); do
        rlm_query --async "Review $f"
    done
    ↓
Wait on sentinel files, aggregate in bash

Limitation: The LLM had to generate the loop structure, and parallelization required autoregressive generation of bash code.

pi-recurse (Pi Extension)

pi (with pi-recurse extension loaded)
    ↓
LLM calls once: recurse({mode: "parallel", tasks: [...]})
    ↓
Extension execute() runs in Node.js:
    ├── Check guardrails (depth, budget, timeout)
    ├── runParallel(tasks, spawnFn, concurrency)
    │   └── Promise.all(concurrent batches)
    ├── Aggregate structured results
    └── Return {results, stats, depth}
    ↓
LLM receives aggregated data, continues reasoning

Advantage: Parallel execution happens in code, not in LLM-generated bash. One tool call → many subagents → aggregated result.

---

Comparison: ypi vs pi-recurse

Feature	ypi (Wrapper)	pi-recurse (Extension)
Entry point	ypi "prompt"	pi (extension auto-loaded)
Parallel spawning	LLM writes bash loop	Code executes Promise.all()
Result aggregation	Bash string manipulation	TypeScript structured objects
Hot reload	Restart ypi process	/reload in pi
Distribution	npm global bin	pi install / git URL
Extension integration	Manual env/PATH setup	Native auto-discovery
Tool disabling	Manual depth checks	Automatic at configured depth
Status visibility	Footer via ypi.ts	Native Pi status bar

---

Development

# Clone and install dependencies
git clone https://github.com/monotykamary/pi-recurse.git
cd pi-recurse
npm install

# Run tests
npm test

# Type check
npm run typecheck

# Build (optional - jiti handles TypeScript at runtime)
npm run build

Testing the Extension

# Install locally
pi install .

# Or test without installing
pi -e ./index.ts

# In pi, test recursion
/recurse-status
recurse({mode: "single", prompt: "What is 2+2?"})

---

Design Principles

1. Single tool call, parallel execution — The LLM describes intent; code handles concurrency
2. Depth-aware degradation — At deep levels, disable recursion to prevent runaway costs
3. Structured over stringly — Full TypeScript types for inputs and outputs
4. Guardrails in code — Budget, timeout, depth checked programmatically
5. Pi-native integration — Use Pi's extension API, not wrapper scripts

---

Related Projects

• ypi — The original bash wrapper that inspired this extension
• pi-messenger — Multi-agent coordination for Pi (another extension)
• pi — The Pi coding agent itself

License

MIT — See LICENSE for details.