pi-rlm-query Extension

Recursive LLM Query extension for pi coding agent.

Enables agent-to-agent delegation with guardrails (depth limits, budget tracking, timeouts, and workspace isolation). This brings ypi-style recursion directly into pi as a native extension.

What It Does

This extension adds rlm_query to pi—a tool that allows the AI to spawn child pi agents when a task is too large for the current context window. Each child gets:

• Fresh context window (empty conversation history)
• Isolated workspace (temp directory, parent files untouched)
• Same capabilities (bash, read, write, edit tools)
• Automatic guardrails (depth, budget, calls, timeout)

Installation

Option 1: Install from Local Directory (Development)

# 1. Build the extension
cd pi-rlm-extension
npm install
npm run build

# 2. Install in pi
pi install /path/to/pi-rlm-extension

# Or for global install
pi install -g /path/to/pi-rlm-extension

Option 2: Copy to Extensions Directory (Manual)

# Build first
npm install
npm run build

# Copy to pi extensions
mkdir -p ~/.pi/agent/extensions/pi-rlm-query
cp -r dist/* ~/.pi/agent/extensions/pi-rlm-query/
cp package.json ~/.pi/agent/extensions/pi-rlm-query/

Option 3: Install from Git (Once Published)

pi install git:github.com/DrOlu/pi-rlm-query

Verification

After installation, start pi and check:

pi
/tools  # Should show: rlm_query, rlm_cost, rlm_status

Or use the command:

/rlm-config  # Shows current settings

Tools Provided

1. rlm_query - Recursive Delegation

Purpose: Delegate a task to a child pi agent.

Parameters:

• task (required): The specific task to delegate
• context (optional): Data to pass to the child (file contents, snippets)
• files (optional): Array of file paths to copy to child's workspace
• timeout (optional): Override timeout in seconds (default: 60)

Example Usage:

# Simple delegation
rlm_query task="Refactor the error handling in src/auth.js"

# With context
rlm_query 
  task="Fix the bug in this function"
  context="function calculateTotal(items) { return items.reduce((a,b) => a+b.price, 0); }"

# With specific files
rlm_query
  task="Update all API calls to use the new endpoint"
  files=["src/api.js", "src/utils.js"]

2. rlm_cost - Budget Check

Purpose: Check how much budget has been used.

Parameters:

• format: "simple" (default) or "json"

Example:

rlm_cost                    # Returns: "$0.0423 spent / $0.50 budget (8.5%)"
rlm_cost format="json"     # Returns detailed breakdown

3. rlm_status - Full System Status

Purpose: Complete status of recursion system.

Returns:

• Depth (current/max/available)
• Budget (spent/total/remaining)
• Calls (used/max/remaining)
• Timeout (elapsed/total/remaining)
• Health check (boolean)

Commands

/rlm-config - Configure Guardrails

View or change RLM settings:

/rlm-config                    # Show current settings
/rlm-config depth 5             # Set max depth to 5
/rlm-config budget 1.00          # Set budget to $1.00
/rlm-config calls 50            # Set max calls to 50
/rlm-config timeout 600         # Set timeout to 10 minutes
/rlm-config model claude-sonnet  # Set child model

Environment Variables

Set these before starting pi to configure defaults:

| Variable | Default | Description | |----------|---------|-------------| | RLM_MAX_DEPTH | 3 | Maximum recursion depth | | RLM_BUDGET | 0.50 | Total budget in dollars | | RLM_MAX_CALLS | 20 | Maximum rlm_query calls | | RLM_TIMEOUT | 300 | Timeout per call in seconds | | RLM_MODEL | claude-sonnet-4 | Model for children | | RLM_PROVIDER | anthropic | Provider for children |

Example:

export RLM_MAX_DEPTH=5
export RLM_BUDGET=2.00
export RLM_MODEL=gpt-4o
pi

How It Works

1. You (or the AI) calls rlm_query with a task
2. Extension checks guardrails: depth, budget, calls, timeout
3. Creates isolated workspace: temp directory for child
4. Copies files: specified files available to child
5. Spawns child pi: runs pi -p (print mode) with system prompt
6. Child executes: uses tools to complete task
7. Returns result: child output goes back to parent
8. Cleans up: temp workspace deleted
9. Updates tracking: budget, call count, depth

Guardrails

| Guardrail | Default | Behavior When Hit | |-----------|---------|-------------------| | Depth | 3 levels | Child cannot spawn more children | | Budget | $0.50 | Returns error, no more calls allowed | | Calls | 20 | Returns error, budget protection | | Timeout | 60s per call | Child process killed |

Comparison: Extension vs ypi

| Feature | ypi (Bash Wrapper) | This Extension | |---------|-------------------|----------------| | Integration | External wrapper | Native pi extension | | Setup | Install separately | pi install | | Portability | Shell-dependent | Cross-platform | | Performance | Spawns bash + pi | Direct pi spawning | | Debugging | Can see shell commands | Logs via pi's system | | Updates | Manual | Via pi package manager | | Compatibility | Works with any pi | Requires pi >= 0.60 |

Example Workflows

1. Large Refactoring

You: "Refactor all error handling in this codebase"

Pi: "This is a large task. Let me break it down:"

rlm_query task="Find all files with error handling" 
  → Returns: ["src/auth.js", "src/api.js", "src/db.js"]

rlm_query 
  task="Refactor error handling in auth.js"
  files=["src/auth.js"]
  → Returns: Updated code

rlm_query 
  task="Refactor error handling in api.js" 
  files=["src/api.js"]
  → Returns: Updated code

rlm_query
  task="Refactor error handling in db.js"
  files=["src/db.js"]
  → Returns: Updated code

Pi: "I've refactored all error handling across 3 files."

2. Parallel Analysis

You: "Security audit this codebase"

Pi: "I'll run parallel security checks:"

rlm_query 
  task="Check for SQL injection vulnerabilities"
  → Result 1

rlm_query 
  task="Check for XSS vulnerabilities"
  → Result 2

rlm_query 
  task="Check for hardcoded secrets"
  → Result 3

Pi: "Combined security report: [aggregated results]"

3. Deep Research

You: "Analyze this 50-file codebase and suggest architecture improvements"

Pi at depth 0: "This is too large. Delegating:"
  → spawns 5 children (depth 1), each analyzes 10 files
  
Each child at depth 1: "Still large. Delegating:"
  → spawns 2 children (depth 2), each analyzes 5 files
  
Leaf children at depth 2 (max depth):
  → Analyze their 5 files directly
  → Return findings to parents
  
Parents at depth 1:
  → Aggregate their children's findings
  → Return to root

Root at depth 0:
  → Combines all findings
  → Presents architecture recommendations

Troubleshooting

Extension not loading

# Check extension is in right place
ls ~/.pi/agent/extensions/pi-rlm-query/

# Should show: index.js, package.json

Tool not found

/tools  # Verify rlm_query is listed

Child spawning fails

# Check pi is in PATH
which pi

# Or set explicitly
export PI_PATH=/usr/local/bin/pi

Budget exhausted quickly

/rlm-config budget 5.00  # Increase budget

License

MIT

Author

Dr. Olu (Seyi Akin)