pi-subagent

Pi CLI(@earendil-works/pi-coding-agent)을 프로그래밍 가능한 코딩 서브 에이전트로 전환하여, 모든 MCP 호스트(ZCode, Claude Code, Cursor 등)가 작업을 위임하고, 세션을 추적하고, 프로세스를 종료할 수 있게 합니다.

pi-subagent는 pi -p --mode json을 7개의 구조화된 도구로 감싸는 경량 MCP 서버입니다: 작업 위임, 결과 수집, 스케줄링 결정, 명명된 세션 관리, 실행 중단. 프로세스 격리, 완전 세션 기반, 동기/비동기 이중 모드.

왜 필요한가

Pi는 최소한의 터미널 코딩 에이전트입니다. 이 프로젝트는 Pi에게 방법론을 가르치는 대신, Pi를 위임 가능한 작업자로 취급합니다: 호스트 에이전트(ZCode / Claude Code)가 언제 위임할지 결정하고, 자체 포함된 작업을 실행하고, 결과를 수집합니다. 하나의 Pi 프로세스 = 하나의 격리된 서브 에이전트 실행.

• 프로세스 격리 — 각 위임은 하나의 pi -p 자식 프로세스를 생성합니다. Pi가 충돌해도 해당 실행에만 영향을 미칩니다.

• 완전 세션 기반 — 모든 작업은 명명된 세션(예: feat-auth)에 바인딩됩니다. 이후 호출은 자동으로 계속됩니다.

• 동기 / 비동기 — 기본값은 async(호스트 도구 호출 시간 초과 방지). pi_status 롱폴링으로 수집.

• 스케줄 가능 — pi_plan은 순수 5단계 결정 함수(거부 / 용량 / 재사용 / 수정 / 모드)이며, 완전히 단위 테스트됨.

• 범용 MCP — 모든 표준 MCP 클라이언트가 로드할 수 있습니다.

Related MCP server: cursor-agent-bridge

아키텍처

┌─────────────────────────────────────────────────────────────┐
│  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+)     │
                   └─────────────────────┘

명확한 경계를 가진 세 개의 계층: 도구 계층(MCP 스키마 + plan() 순수 함수) / 세션 레지스트리(상태 + 영속성 + 편집) / 러너(pi 생성, NDJSON 파싱, 프로세스 테이블).

도구

검토 루프: pi_task_plan 후 pi_status(runId)로 수집합니다. 실행이 완료되면 서버는 검토 실행임을 감지하고 _plan-reviewed.md를 파싱하여 planVerdict / planReviewedPath를 작업에 저장합니다. 단계 프롬프트는 자동으로 검토된 계획과 통과된 의존성 단계의 출력 파일을 포함합니다.

비동기 단계: pi_task_stage_run에 mode: "async"를 전달하면 전체 실행 동안 도구 호출을 차단하지 않습니다(MCP 호스트가 짧은 도구 시간 초과를 적용할 때 권장). pi_task_stage_collect(taskId, stageId)로 수집합니다. 실패한 시도는 새 세션 이름으로 재전달되어 기록 오염을 방지합니다. 3회 실패 후 단계는 manual이 되며 결정 패널(promptHintOverride를 통한 retry_with_new_hint 지원)이 표시됩니다.

재시작 복구: 동일한 taskId로 pi_task_create를 다시 실행하면 충돌 대신 병합됩니다. 출력 파일이 이미 존재하고 검증을 통과한 단계는 자동으로 passed로 표시되므로, 중단된 작업은 tasks.json을 수동 편집하지 않고 재개할 수 있습니다.

세션 모델

• 각 세션은 사람이 읽을 수 있는 이름 + Pi의 UUID + cwd + goal을 가집니다.

• 첫 번째 pi_delegate가 세션을 생성합니다(goal 필수). 이후 호출은 자동으로 계속됩니다.

• 레지스트리는 ~/.pi-subagent/registry.json에 영속화됩니다(원자적 쓰기, 재시작 시 중단된 running 레코드는 error로 수정).

• 동시성 상한: 4개의 실행 중인 런. 단일 세션은 동시에 실행되지 않습니다.

• 작업은 ~/.pi-subagent/tasks.json에 영속화됩니다(원자적 쓰기, 재시작 시 실행 중인 단계는 failed(interrupted_by_restart)로 수정).

설치

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

전제 조건: pi CLI가 설치되어 있고(npm i -g @earendil-works/pi-coding-agent) PATH에 있어야 합니다.

MCP 호스트 구성

MCP 클라이언트 구성에 추가:

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

선택적 환경 변수:

• PI_SUBAGENT_REGISTRY — 레지스트리 경로(기본값 ~/.pi-subagent/registry.json)

• PI_BIN — pi 실행 파일 재정의(테스트에서 사용)

테스트

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

테스트는 가짜 pi(test/fixtures/fake-pi.sh)를 사용하며 다음을 다룹니다: 비동기/동기, 시간 초과, 종료, 세션 생성 실패, 다중 대기자, 진행 상한, 스케줄링 규칙(테이블 기반 + 100회 반복 속성 테스트), 레지스트리 영속성, 편집 등.

프로젝트 구조

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

설계 및 프로세스

이 프로젝트는 협업 설계 + 구현 전 4차례의 외부 검토를 거쳤습니다. 사양과 계획은 docs/ 아래에 커밋되어 있습니다:

• docs/design.md — 전체 설계 사양(아키텍처, 도구 계약, 오류 처리, 스케줄러 규칙, 테스트 전략). 모든 계약은 검토 노트(R1–R4)로 추적 가능합니다.

• docs/implementation-plan.md — 19개의 TDD 작업(실패 테스트 작성 → 구현 → 통과 → 커밋).

모든 주요 설계 결정은 실제 pi -p 출력 프로빙과 외부 검토에 기반합니다:

• cwd ≠ 세션 저장소 — spawn({ cwd })는 작업 디렉터리를 제어합니다. Pi의 세션 파일은 기본 위치를 사용합니다(프로젝트를 오염시키지 않음).

• 비동기 기본 + 핸드셰이크 — 새 세션은 sessionStartTimeoutMs로 Pi의 session 이벤트를 기다린 후 반환하므로 호스트는 항상 실제 piSessionId를 얻습니다.

• 다단계 스케줄러 — plan()은 거부 → 용량 → 재사용 → 수정 → 모드 순서이며, 수정자는 첫 번째 일치가 아닌 누적됩니다(검토 1차에서 얻은 교훈).

• 진행 편집 — 도구 결과는 저장 전에 잘리고 토큰/키가 제거됩니다.

상태

작동하는 구현, 140개의 통과 테스트. 아직 npm에 게시되지 않음 — tsx로 소스에서 실행.

라이선스

MIT