npm

ypi — a recursive coding agent built on Pi.

Named after the Y combinator from lambda calculus — the fixed-point combinator that enables recursion. ypi is Pi that can call itself. (rpi already has another connotation.)

Inspired by Recursive Language Models (RLM), which showed that an LLM with a code REPL and a llm_query() function can recursively decompose problems, analyze massive contexts, and write code — all through self-delegation.

Pi already has a bash REPL. We add one function — rlm_query — and a system prompt that teaches Pi to use it recursively. Each child gets its own jj workspace for file isolation. That's the whole trick.

┌──────────────────────────────────────────┐
│ ypi (depth 0) │
│ Tools: bash, rlm_query │
│ Workspace: default │
│ │
│ > grep -n "bug" src/*.py │
│ > sed -n '50,80p' src/app.py \ │
│ | rlm_query "Fix this bug" │
│ │ │
│ ▼ │
│ ┌────────────────────────────┐ │
│ │ ypi (depth 1) │ │
│ │ Workspace: jj isolated │ │
│ │ Edits files safely │ │
│ │ Returns: patch on stdout │ │
│ └────────────────────────────┘ │
│ │
│ > jj squash --from <child-change> │
│ # absorb the fix into our working copy │
└──────────────────────────────────────────┘

# npm (global)
npm install -g ypi
# or run without installing
npx ypi "What does this repo do?"
bunx ypi "What does this repo do?"
# or curl
curl -fsSL https://raw.githubusercontent.com/rawwerks/ypi/master/install.sh | bash
# or manual
git clone https://github.com/rawwerks/ypi.git && cd ypi
git submodule update --init --depth 1
export PATH="$PWD:$PATH"

# Interactive
ypi
# One-shot
ypi "Refactor the error handling in this repo"
# Different model
ypi --provider anthropic --model claude-sonnet-4-5-20250929 "What does this codebase do?"

Three pieces (same architecture as Python RLM):

Depth 0 (root) → full Pi with bash + rlm_query
 Depth 1 (child) → full Pi with bash + rlm_query, own jj workspace
 Depth 2 (leaf) → full Pi with bash, but no rlm_query (max depth)

File isolation with jj: Each recursive child gets its own jj workspace. The parent's working copy is untouched. Review child work with jj diff -r <change-id>, absorb with jj squash --from <change-id>.

The design has three properties that compound:

1. Self-similarity — Every depth runs the same prompt, same tools, same agent. No specialized "scout" or "planner" roles. The intelligence is in decomposition, not specialization. The system prompt teaches one pattern — size-first → search → chunk → delegate → combine — and it works at every scale.

2. Self-hosting — The system prompt (SECTION 6) contains the full source of rlm_query. The agent reads its own recursion machinery. When it modifies rlm_query, it's modifying itself. This isn't a metaphor — it's the actual execution model.

3. Bounded recursion — Five concentric guardrails (depth limit, PATH scrubbing, call count, budget, timeout) guarantee termination. The system prompt also installs cognitive pressure: deeper agents are told to be more conservative, preferring direct action over spawning more children.

4. Symbolic access — Anything the agent needs to manipulate precisely is a file, not just tokens in context. $CONTEXT holds the data, $RLM_PROMPT_FILE holds the original prompt, and hashline provides line-addressed edits. Agents grep/sed/cat instead of copying tokens from memory.

The agent can check spend at any time:

rlm_cost # "0ドル.042381"
rlm_cost --json # {"cost": 0.042381, "tokens": 12450, "calls": 3}

ypi is a thin layer on top of Pi. We strive not to break or duplicate what Pi already does:

If Pi changes how sessions or extensions work, our guardrail tests should catch it.

ypi/
├── ypi # Launcher: sets up env, starts Pi as recursive agent
├── rlm_query # The recursive sub-call function (Pi's analog of rlm llm_query())
├── SYSTEM_PROMPT.md # Teaches the LLM to be recursive + edit code
├── AGENTS.md # Meta-instructions for the agent (read by ypi itself)
├── Makefile # test targets
├── tests/
│ ├── test_unit.sh # Mock pi, test bash logic (no LLM, fast)
│ ├── test_guardrails.sh # Test guardrails (no LLM, fast)
│ └── test_e2e.sh # Real LLM calls (slow, costs ~0ドル.05)
├── pi-mono/ # Git submodule: upstream Pi coding agent
└── README.md

This repo uses jj for version control. Git is only for GitHub sync.

jj status # What's changed
jj describe -m "message" # Describe current change
jj new # Start a new change
jj bookmark set master # Point master at current change
jj git push # Push to GitHub

Never use git add/commit/push directly. jj manages git under the hood.

make test-fast # unit + guardrails
make test-extensions # extension compatibility with installed pi
make pre-push-checks # shared local/CI gate (recommended before push)
make test-e2e # real LLM calls, costs money
make test # all of the above

Install hooks once per clone to run checks automatically on git push:

make install-hooks

Release/update helper:

make release-preflight # same checks + upstream dry-run in one command

Before any change to rlm_query: run make test-fast. After: run it again. rlm_query is a live dependency of the agent's own execution — breaking it breaks the agent.

CI helper commands:

make ci-status N=15 # recent workflow runs
make ci-last-failure # dump latest failing workflow log

ypi went through four approaches before landing on the current design:

1. Tool-use REPL (exp 010/012) — Pi's completeWithTools(), ReAct loop. 77.6% on LongMemEval.
2. Python bridge — HTTP server between Pi and Python RLM. Too complex.
3. Pi extension — Custom provider with search tools. Not true recursion.
4. Bash RLM (rlm_query + SYSTEM_PROMPT.md) — True recursion via bash. Current approach.

The key insight: Pi's bash tool is the REPL. rlm_query is llm_query(). No bridge needed.

• Pi coding agent — the underlying agent
• Recursive Language Models — the library that inspired this
• rlm-cli — Python RLM CLI (budget, timeout, model routing)