pi-subagent

Turn the Pi CLI (@earendil-works/pi-coding-agent) into a programmierbaren Coding-Sub-Agenten, dem jeder MCP-Host (ZCode, Claude Code, Cursor, …) Aufgaben delegieren, Sitzungen verfolgen und Prozesse beenden kann.

pi-subagent ist ein schlanker MCP-Server, der pi -p --mode json in 7 strukturierte Tools kapselt: Aufgaben delegieren, Ergebnisse abholen, Planungsentscheidungen treffen, benannte Sitzungen verwalten und Läufe abbrechen. Prozessisoliert, vollständig sitzungsbasiert, Sync/Async-Dualmodus.

Warum

Pi ist ein minimaler Terminal-Coding-Agent. Anstatt Pi Methodik beizubringen, behandelt dieses Projekt Pi als delegierbaren Arbeiter: Ein Host-Agent (ZCode / Claude Code) entscheidet, wann er delegiert, startet eine eigenständige Aufgabe und holt das Ergebnis ab. Ein Pi-Prozess = ein isolierter Sub-Agenten-Lauf.

• Prozessisolation — jede Delegation startet einen pi -p-Kindprozess. Ein Pi-Absturz betrifft nur diesen Lauf.

• Vollständig sitzungsbasiert — jede Aufgabe ist an eine benannte Sitzung gebunden (z. B. feat-auth); nachfolgende Aufrufe setzen automatisch fort.

• Sync / Async — Standard ist async (vermeidet Timeouts bei Host-Tool-Aufrufen); Ergebnisse mit pi_status per Long-Poll abholen.

• Planbar — pi_plan ist eine reine 5-stufige Entscheidungsfunktion (reject / capacity / reuse / modify / mode), vollständig unit-getestet.

• Universelles MCP — jeder Standard-MCP-Client kann es laden.

Related MCP server: cursor-agent-bridge

Architektur

┌─────────────────────────────────────────────────────────────┐
│  MCP Host (ZCode / Claude Code / Pi / Cursor …)              │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP (JSON-RPC over stdio)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  pi-subagent-server  (Node/TS)                                │
│  ┌────────────┐  ┌──────────────┐  ┌────────────────────┐   │
│  │ Tool layer │  │ Session      │  │ Pi runner          │   │
│  │ (7 tools)  │─▶│ registry     │─▶│ (spawn pi -p)      │   │
│  │ + plan()   │  │ + persist    │  │ parse agent_end    │   │
│  └─────┬──────┘  │ + _snapshot  │  │ + tool_execution   │   │
│        │         └──────────────┘  └─────────┬──────────┘   │
│        │                           ┌────────▼─────────┐     │
│        └───────────────────────────│ Run registry     │     │
│           (kill)                   │ + process-table  │     │
│                                   └──────────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            │ child_process.spawn({ cwd })
                            ▼
                   ┌─────────────────────┐
                   │  pi CLI (0.77+)     │
                   └─────────────────────┘

Drei Schichten mit klaren Grenzen: Tool-Schicht (MCP-Schema + plan()-reine Funktion) / Sitzungsregister (Zustand + Persistenz + Redaktion) / Runner (pi starten, NDJSON parsen, Prozesstabelle).

Tools

Review-Schleife: Nach pi_task_plan das Ergebnis mit pi_status(runId) abholen. Wenn der Lauf endet, erkennt der Server, dass es sich um einen Review-Lauf handelt, parst _plan-reviewed.md und speichert planVerdict / planReviewedPath in der Aufgabe. Stufen-Prompts enthalten automatisch den überprüften Plan und die Ausgabedateien bestandener Abhängigkeitsstufen.

Async-Stufen: Übergeben Sie mode: "async" an pi_task_stage_run, um einen Tool-Aufruf nicht für den gesamten Lauf zu blockieren (empfohlen, wenn der MCP-Host ein kurzes Tool-Timeout erzwingt). Ergebnis mit pi_task_stage_collect(taskId, stageId) abholen. Fehlgeschlagene Versuche werden unter einem neuen Sitzungsnamen erneut ausgelöst, um eine Kontamination des Verlaufs zu vermeiden; nach 3 Fehlversuchen wechselt die Stufe auf manual mit einem Entscheidungsfeld (retry_with_new_hint wird über promptHintOverride unterstützt).

Neustart-Wiederherstellung: Ein erneutes Ausführen von pi_task_create mit derselben taskId führt zu einer Zusammenführung statt zu einem Konflikt. Stufen, deren Ausgabedatei bereits existiert und die Validierung besteht, werden automatisch als passed markiert, sodass unterbrochene Aufgaben ohne manuelle Bearbeitung von tasks.json fortgesetzt werden.

Sitzungsmodell

• Jede Sitzung hat einen menschenlesbaren Namen + Pi's UUID + cwd + goal.

• Der erste pi_delegate-Aufruf erstellt die Sitzung (goal erforderlich); spätere Aufrufe setzen automatisch fort.

• Das Register wird in ~/.pi-subagent/registry.json gespeichert (atomarer Schreibvorgang; beim Neustart werden unterbrochene running-Datensätze zu error korrigiert).

• Parallelitätslimit: 4 laufende Läufe; eine einzelne Sitzung wird nie parallel ausgeführt.

• Aufgaben werden in ~/.pi-subagent/tasks.json gespeichert (atomarer Schreibvorgang; laufende Stufen werden beim Neustart zu failed(interrupted_by_restart) korrigiert).

Installation

git clone <this-repo> && cd pi-subagent
npm install

Voraussetzung: Die pi-CLI ist installiert (npm i -g @earendil-works/pi-coding-agent) und im PATH.

MCP-Host konfigurieren

Fügen Sie zu Ihrer MCP-Client-Konfiguration hinzu:

{
  "mcpServers": {
    "pi-subagent": {
      "command": "npx",
      "args": ["tsx", "/abs/path/to/pi-subagent/src/server.ts"]
    }
  }
}

Optionale Umgebungsvariablen:

• PI_SUBAGENT_REGISTRY — Pfad zum Register (Standard ~/.pi-subagent/registry.json)

• PI_BIN — überschreibt die pi-Ausführungsdatei (für Tests verwendet)

Test

npm test           # full suite (140 tests)
npm run test:fast  # dot reporter

Tests verwenden ein Fake-pi (test/fixtures/fake-pi.sh) und decken ab: async/sync, Timeout, Kill, Sitzungserstellungsfehler, Multi-Waiter, Fortschrittslimit, Planungsregeln (tabellengetrieben + 100-Iteration-Property-Tests), Registerpersistenz, Redaktion usw.

Projektstruktur

src/
├── types.ts                 # all shared types + error codes
├── errors.ts                # ToolError helpers
├── runner/                  # parse.ts, argv.ts, spawn.ts, process-table.ts
├── registry/                # session.ts, run.ts, persist.ts, redact.ts
├── scheduler/               # keywords.ts, plan.ts (5-stage pure function)
├── tools/                   # delegate, status, plan-tool, session, kill
└── server.ts                # MCP entry (stdio)
skills/pi-subagent/          # SKILL.md + delegation-patterns (strategy layer)
test/                        # fixtures/ + *.test.ts
docs/                        # design.md (spec) + implementation-plan.md

Design & Prozess

Dieses Projekt durchlief vor der Implementierung ein kollaboratives Design + 4 Runden externer Überprüfung. Die Spezifikation und der Plan sind unter docs/ eingecheckt:

• docs/design.md — vollständige Design-Spezifikation (Architektur, Tool-Verträge, Fehlerbehandlung, Planungsregeln, Teststrategie). Jeder Vertrag ist auf eine Review-Notiz (R1–R4) zurückführbar.

• docs/implementation-plan.md — 19 TDD-Aufgaben (fehlschlagenden Test schreiben → implementieren → bestehen → committen).

Wichtige Designentscheidungen, alle gestützt auf echte Untersuchung der pi -p-Ausgabe und externe Überprüfung:

• cwd ≠ Sitzungsspeicher — spawn({ cwd }) steuert das Arbeitsverzeichnis; Pi's Sitzungsdateien verwenden ihren Standardort (verschmutzt das Projekt nicht).

• Async-Standard + Handshake — neue Sitzungen warten auf Pi's session-Ereignis, bevor sie zurückkehren (mit einem sessionStartTimeoutMs), sodass der Host immer eine echte piSessionId erhält.

• Mehrstufen-Planer — plan() ist reject → capacity → reuse → modify → mode, wobei Modifikatoren stapeln statt zuerst zu treffen (eine Lektion aus Runde 1 der Überprüfung).

• Fortschritts-Redaktion — Tool-Ergebnisse werden gekürzt und von Tokens/Schlüsseln bereinigt, bevor sie gespeichert werden.

Status

Funktionierende Implementierung, 140 bestandene Tests. Noch nicht auf npm veröffentlicht — aus dem Quellcode über tsx ausführen.

Lizenz

MIT