pi-subagents

pi-subagents

Pi가 집중된 하위 에이전트 (child agents)에게 작업을 위임할 수 있게 합니다. 코드 리뷰 (code review), 탐색 (scouting), 구현 (implementation), 병렬 감사 (parallel audits), 저장된 워크플로우 (saved workflows), 백그라운드 작업 (background jobs) 등 두 번째 또는 세 번째 모델의 시선이 도움이 되는 모든 작업에 사용하세요.

pi-subagents-chain.mp4

pi install npm:pi-subagents

이것이 유일하게 요구되는 단계입니다. 선택적인 구성 요소들은 나중에 추가할 수 있습니다.

에이전트를 생성하거나, 설정을 작성하거나, 슬래시 명령어 (slash commands)를 배울 필요가 없습니다. 설치 후에는 Pi에게 평이한 언어로 위임을 요청하세요:

Use reviewer to review this diff.
(reviewer를 사용하여 이 diff를 리뷰해줘.)

Ask oracle for a second opinion on my current plan.
(현재 계획에 대해 oracle에게 제2의 의견을 물어봐줘.)

Use scout to understand this code based on our discussion then ask me clarification questions.
(우리 대화를 바탕으로 scout를 사용하여 이 코드를 이해한 다음, 나에게 명확한 질문을 해줘.)

Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity.
(병렬 리뷰어 (parallel reviewers)를 실행해줘: 하나는 정확성, 하나는 테스트, 하나는 불필요한 복잡성을 위해.)

이것만으로 시작하기에 충분합니다.

Pi는 부모 세션 (parent session)입니다. 하위 에이전트 (subagent)는 자체적인 작업이 있는 집중된 자식 Pi 세션입니다.

하위 에이전트를 요청하면, Pi는 자식 세션을 시작하고, 작업을 부여하며, 결과를 다시 가져옵니다. 포그라운드 (Foreground) 실행은 대화창에 스트림으로 나타납니다. 백그라운드 (Background) 실행은 계속 작업을 수행하며 나중에 확인할 수 있습니다.

확장 프로그램을 설치한다고 해서 백그라운드에서 자동 리뷰어가 시작되는 것은 아닙니다. 이는 Pi에게 위임 도구 (delegation tool)를 제공할 뿐입니다. 모든 구현 사항을 리뷰하고 싶다면, 프롬프트 (prompt)에 명시하거나 프로젝트 지침 (project instructions)에 넣으세요:

When you finish implementing, run a reviewer subagent before summarizing.
(구현을 마칠 때, 요약하기 전에 reviewer 하위 에이전트를 실행해줘.)

다음은 대부분의 일상적인 사용 사례를 다룹니다:

Ask oracle for a second opinion on my current plan. Challenge assumptions and tell me what I might be missing.
(현재 계획에 대해 oracle에게 제2의 의견을 물어봐줘. 가설에 이의를 제기하고 내가 놓치고 있을 수 있는 것이 무엇인지 말해줘.)

Use oracle to help solve this hard bug. Have it inspect the code and propose the best next move before we edit anything.
(이 어려운 버그를 해결하는 데 oracle을 사용해줘. 우리가 무엇을 수정하기 전에 코드를 검사하고 최선의 다음 단계를 제안하게 해줘.)

Run parallel reviewers on this diff. I want one focused on correctness, one on tests, and one on unnecessary complexity.
(이 diff에 대해 병렬 리뷰어를 실행해줘. 하나는 정확성, 하나는 테스트, 하나는 불필요한 복잡성에 집중하길 원해.)

Have worker implement this approved plan. Afterward, run parallel reviewers, summarize their feedback, and apply the fixes that make sense.
(worker가 이 승인된 계획을 구현하게 해줘. 그 후, 병렬 리뷰어를 실행하고, 그들의 피드백을 요약한 뒤, 타당한 수정 사항을 적용해줘.)

리뷰어가 수행할 가치가 있는 수정 사항을 더 이상 찾지 못할 때까지, 최대 3라운드 동안 이 변경 사항에 대해 리뷰 루프 (review loop)를 실행해줘.

scout를 사용하여 인증 흐름 (auth flow)을 파악한 다음, planner가 이를 구현 계획 (implementation plan)으로 전환하게 해줘.

이것들은 일반적인 Pi 요청입니다. Pi는 subagent를 호출할지, 어떤 에이전트 (agent)를 사용할지, 그리고 체인 (chain) 방식이나 병렬 실행 (parallel run) 방식 중 무엇이 적절할지를 결정합니다.

원하는 작업	자연스럽게 요청하기
제2의 의견 얻기	“oracle에게 이 계획을 검토하고 가설에 이의를 제기하도록 요청해줘.”
...
이 확장 프로그램 (extension)은 즉시 사용할 수 있는 내장 에이전트 (builtin agents)와 함께 제공됩니다.

에이전트 (Agent)	다음과 같은 경우에 사용하세요...
scout
빠른 로컬 코드베이스 정찰 (recon): 관련 파일, 엔트리 포인트 (entry points), 데이터 흐름 (data flow), 리스크, 그리고 다른 에이전트가 시작해야 할 위치 파악.
researcher
출처를 포함한 웹/문서 조사 (research): 공식 문서, 사양 (specs), 벤치마크 (benchmarks), 최근 변경 사항, 그리고 간결한 조사 보고서 작성.
planner
기존 컨텍스트 (context)로부터 구체적인 구현 계획 수립. 코드를 수정하는 것이 아니라, 읽고 계획을 세워야 함.
worker
승인된 oracle 인계 (handoffs)를 포함한 구현 작업. 파일을 수정하고, 검증하며, 승인되지 않은 결정에 대해서는 추측하는 대신 에스컬레이션 (escalate)함.
reviewer
코드 리뷰 및 작은 수정 사항 처리. 작업/계획 대비 구현 사항, 테스트, 엣지 케이스 (edge cases), 그리고 단순성을 확인.
context-builder
계획 수립 전의 강력한 설정 단계: 코드 컨텍스트를 수집하고 context.md 및 meta-prompt.md와 같은 인계 자료를 작성.
oracle
행동하기 전의 제2의 의견. 가설에 이의를 제기하고, 이탈 (drift)을 포착하며, 수정 없이 가장 안전한 다음 단계를 권장.
delegate
부모 세션과 유사하게 동작하는 하위 에이전트 (child agent)가 필요할 때 사용하는 가벼운 범용 위임자.

간단한 원칙: 코드를 이해하기 전에는 scout를, 외부 사실을 신뢰하기 전에는 researcher를, 더 큰 변경을 하기 전에는 planner를, 구현을 위해서는 worker를, 확인을 위해서는 reviewer를, 그리고 결정 자체가 위험하다고 느껴질 때는 oracle을 사용하세요.

내장 에이전트 (Builtin agents)는 기본적으로 사용자의 현재 Pi 기본 모델 (default model)을 상속받습니다. 이는 새로운 설치 시 사용자가 구성하지 않았을 수도 있는 제공자 (provider)에 의존하는 상황을 방지하기 위함입니다. 특정 역할 (role)이 특정 모델을 사용하도록 하려면, 번들된 에이전트 파일을 복사하는 대신 오버라이드 (override)를 설정하세요.

단일 실행에 대해서는 명령어에 오버라이드를 포함하세요:

/run reviewer[model=anthropic/claude-sonnet-4:high] "Review this diff"

지속적인 오버라이드를 위해서는 설정을 편집하세요. 다음 예시는 모든 곳에서 reviewer를 고정하고, 제공자 장애를 대비한 백업 모델을 추가하며, 다른 내장 에이전트들은 사용자의 일반적인 기본 모델을 유지하도록 합니다:

{
"subagents": {
"agentOverrides": {
...

사용자 오버라이드 (user override)를 위해서는 ~/.pi/agent/settings.json을, 프로젝트 오버라이드 (project override)를 위해서는 .pi/settings.json을 사용하세요. 동일한 agentOverrides 블록을 통해 tools (도구), skills (기술), 상속된 컨텍스트 (inherited context), 프롬프트 텍스트 (prompt text)를 변경하거나 내장 에이전트를 비활성화할 수 있습니다. 완전히 다른 에이전트를 원한다면 동일한 이름으로 사용자 또는 프로젝트 에이전트를 생성하세요. 일반적인 미세 조정 (tweaks)의 경우에는 오버라이드를 권장합니다.

포그라운드 실행 (Foreground runs)은 실행되는 동안 대화창에 진행 상황을 스트리밍합니다.

백그라운드 실행 (Background runs)은 제어권이 사용자에게 돌아온 후에도 계속 작동합니다. subagent({ action: "status" })를 통해 활성 실행을 확인하거나, subagent({ action: "status", id: "..." })를 통해 특정 실행을 확인할 수 있습니다.

또한 이들은 컴팩트한 비동기 위젯 (async widget)을 보여주고 완료 알림을 보냅니다. 병렬 백그라운드 실행 (Parallel background runs)은 가짜 체인 단계 (fake chain steps) 대신 에이전트별 진행 상황을 보여줍니다. 병렬 그룹이 포함된 체인 (Chains with parallel groups)은 진행 상황과 결과에서 그룹화된 형태를 유지하므로, 실패하거나 일시 중지된 에이전트가 완료된 에이전트 옆에 계속 표시됩니다. 자식 에이전트가 tools: subagent를 통해 명시적으로 팬 아웃 (fan out)이 허용된 경우, 해당 중첩 실행 (nested runs)은 자식 프로세스 내부에 숨겨지는 대신 메인 상태 트리 (status tree)의 해당 부모 자식 아래에 나타납니다.

자연어로 다음과 같이 요청할 수도 있습니다:

Show me the current async runs.

설정이 잘못된 것 같다면 다음을 실행하세요:

/subagents-doctor

또는 다음과 같이 물어보세요:

Check whether subagents and intercom are set up correctly.

오케스트레이션 (orchestration)을 런타임 워크플로 모드 (runtime workflow mode)가 아닌, 부모 에이전트 (parent-agent)의 가이드로 사용하세요. 구현 작업을 위해 권장되는 루프 (loop)는 다음과 같습니다:

명확화 (clarify) → 플래너 (planner) → 워커 (worker) → 새로운 검토자 (fresh reviewers) → 워커 (worker)

이 패턴을 반복 가능하게 만들고 싶을 때는 아래의 선택적 프롬프트 단축키 (prompt shortcuts)를 사용하세요.

패키징된 planner, worker, oracle은 실행 시 context를 생략하면 기본적으로 포크된 컨텍스트 (forked context)를 사용합니다. 의도적으로 새로운 자식 실행 (fresh child run)을 원하는 경우에는 context: "fresh"를 전달하세요.

자식 안전 경계 (Child-safety boundaries)는 런타임 (runtime)에 강제됩니다. 생성된 자식 세션 (child sessions)은 번들로 포함된 pi-subagents 스킬 (skill)을 받지 않습니다. 또한, 포크된 자식 컨텍스트 필터링 (forked child context filtering)을 통해 일반적인 산문 (prose)과 관련 없는 도구 호출/결과 (tool calls/results)는 보존하면서, 부모 전용 서브에이전트 (subagent) 아티팩트 (artifacts) (이전의 숨겨진 오케스트레이션 지침 메시지, 슬래시/상태/제어 메시지, 그리고 이전 부모의 subagent 도구 호출/도구 결과 이력 포함)를 제거합니다. 기본적으로 자식은 subagent 도구를 등록하지 않으며, 자신이 부모 오케스트레이터 (parent orchestrator)가 아니며 서브에이전트를 제안하거나 실행해서는 안 된다는 경계 지침 (boundary instructions)을 받습니다. 명시적인 예외는 해결된 내장 도구 (resolved builtin tools)에 subagent가 포함된 에이전트입니다. 해당 자식은 부모가 할당한 팬아웃 (fanout) 작업을 위해 자식 안전 subagent 도구를 받게 되지만, 여전히 maxSubagentDepth에 의해 제한됩니다.

이 패키지에는 일반적인 워크플로 (workflows)를 위한 재사용 가능한 프롬프트 템플릿 (prompt templates)이 포함되어 있습니다. 반드시 필요하지는 않지만, 매번 동일한 형태를 유지하고 싶을 때 유용합니다:

프롬프트 (Prompt)	용도 (Use it for)
/parallel-review	서로 다른 관점을 가진 새로운 컨텍스트의 리뷰어 (reviewers)를 실행한 후, 수정 사항을 종합(synthesize)합니다.
/review-loop	결과가 깨끗해지거나 제한에 도달할 때까지 부모가 제어하는 워커 (worker), 리뷰어 (reviewer), 수정 워커 (fix-worker) 사이클을 실행합니다.
/parallel-research	researcher와 scout를 결합하여 외부 증거, 로컬 코드 컨텍스트 (code context), 그리고 실질적인 트레이드오프 (tradeoffs)를 조사합니다.
/parallel-context-build	context-builder 에이전트 (agents)를 병렬로 실행하여 계획 전달 컨텍스트 (planning handoff context)와 메타 프롬프트 (meta-prompts)를 생성합니다.
/parallel-handoff-plan	외부 조사와 context-builder 패스 (passes)를 결합하여 구현 전달 계획 (implementation handoff plan) 및 메타 프롬프트를 생성합니다.
/gather-context-and-clarify	먼저 스카우트/리서치 (scout/research)를 수행한 후, 중요한 확인 질문 (clarification questions)을 사용자에게 요청합니다.
/parallel-cleanup	구현 (implementation) 이후 리뷰 전용 정리 (cleanup) 패스를 실행합니다.

/parallel-review 또는 /parallel-cleanup에 autofix를 추가하면, 리뷰어들이 결과를 반환한 후 지금 수행할 가치가 있는 종합된 수정 사항들만 적용할 수 있습니다.

pi-subagents는 pi-intercom 없이도 작동합니다. 자식 에이전트 (child agents)가 실행되는 동안 부모 Pi 세션 (Pi session)과 다시 통신하기를 원하는 경우에만 pi-intercom을 설치하세요.

pi install npm:pi-intercom

대부분의 사용자는 intercom을 직접 호출하지 않습니다. pi-intercom이 설치되면, pi-subagents는 자식 에이전트에게 부모 세션으로 돌아가는 프라이빗 조정 채널 (private coordination channel)을 자동으로 제공할 수 있습니다. 이 브릿지 (bridge)는 일반적인 pi install npm:pi-intercom 패키지 설치뿐만 아니라 레거시 로컬 확장 프로그램 체크아웃 (legacy local extension checkouts)도 인식합니다.

자식 에이전트가 추측하는 대신 결정이 필요할 수 있는 작업에 이를 사용하세요:

이 구현을 백그라운드에서 실행하세요. 만약 워커 (worker)가 차단되거나 제품 결정 (product decision)이 필요하다면, intercom을 통해 나에게 질문하도록 하세요.

오라클 (oracle)에게 이 계획을 검토하도록 요청하세요. 만약 내가 내려야 할 결정이 보인다면, 임의로 가정하지 말고 나에게 질문하도록 하세요.

자식 에이전트는 하나의 전용 조정 도구 (coordination tool)를 사용할 수 있습니다:

contact_supervisor: 자식이 작업을 위임한 부모/감독 세션 (parent/supervisor session)에 연락합니다. reason: "need_decision"을 사용하세요.

차단형 결정 (blocking decisions) 또는 명확화 (clarification)가 필요한 경우 reason: "need_decision"을 사용하고, 발견된 사항이 계획을 변경하여 짧은 비차단형 업데이트 (non-blocking updates)가 필요한 경우 reason: "progress_update"를 사용하세요. 유일한 충돌이 '검토 전용/수정 불가 (review-only/no-edit)'와 '진행 상황 기록 (progress-writing)' 또는 '아티팩트 기록 (artifact-writing)' 지침 사이의 충돌일 경우에는 명확화를 요청하지 마세요. 수정 불가 (no-edit) 지침이 우선합니다.

자식 측 (child-side)의 루틴 완료 핸드오프 (routine completion handoffs)는 여전히 기대되지 않습니다. 인터콤 브리지 (intercom bridge)가 활성화되면, 부모 측 pi-subagents는 pi-intercom을 통해 그룹화된 완료 결과 (grouped completion results)를 전송합니다:

• 포그라운드 부모 subagent 실행당 하나의 그룹화된 메시지
• 완료된 비동기 결과 파일 (async result file)당 하나의 메시지

전달이 확인된 (acknowledged) 포그라운드 전달은 아티팩트/세션 경로가 포함된 간결한 영수증 (compact receipt)을 반환하며, 확인되지 않은 경우 일반적인 전체 출력 (full output)이 유지됩니다. 그룹화된 메시지에는 자식 인터콤 대상 (child intercom targets), 전체 자식 요약 (full child summaries), 그리고 해당 자식을 실행시킨 부모 자식 아래의 간결한 중첩 자식 요약 (compact nested child summaries)이 포함됩니다.

자식이 정지된 것처럼 보이거나 주의가 필요한 경우, 부모 세션에 subagent({ action: "status" }) 확인, 실행 중단, 또는 자식에게 넛지 (nudging)를 보내는 것과 같은 유용한 다음 작업이 포함된 주의 알림 (needs-attention notices)이 나타날 수 있습니다.

메시지가 나타나지 않으면 다음을 실행하세요:

/subagents-doctor

일반적인 사용을 위해서는 아무것도 설정할 필요가 없습니다. 고급 사용자는 아래의 설정 (configuration) 섹션에서 intercomBridge를 통해 브리지를 조정할 수 있습니다.

이제 이 플러그인을 사용할 수 있을 만큼 충분한 정보를 알게 되었습니다. 이 README의 나머지 부분은 정확한 명령 구문 (command syntax), 커스텀 에이전트 (custom agents), 저장된 체인 (saved chains), 워크트리 (worktrees) 및 설정 (configuration)에 대한 참조 자료입니다.

정확한 구문이 필요한 시점 전까지는 이 섹션을 건너뛰셔도 됩니다.

명령 (Command)	설명 (Description)
/run <agent> [task]	에이전트 하나를 실행합니다. 독립적인 에이전트의 경우 태스크를 생략하세요.
/chain agent1 "task1" -> agent2 "task2"	에이전트들을 순차적으로 실행합니다.
/parallel agent1 "task1" -> agent2 "task2"	에이전트들을 병렬로 실행합니다.
/run-chain <chainName> -- <task>	저장된 .chain.md 또는 .chain.json 워크플로우 (workflow)를 시작합니다.
/subagents-doctor	읽기 전용 설정 진단 (setup diagnostics)을 보여줍니다.

명령어는 에이전트 이름을 로컬에서 검증하고, 탭 완성(tab completion)을 지원하며, 결과를 대화로 다시 보냅니다.

단계(steps)를 구분하고 각 단계에 고유한 작업(task)을 부여하려면 ->를 사용하세요:

/chain scout "scan the codebase" -> planner "create an implementation plan"
/parallel scanner "find security issues" -> reviewer "check code style"

큰따옴표와 작은따옴표 모두 작동합니다. 또한 구분자(delimiter)로 --를 사용할 수도 있습니다:

/chain scout -- scan code -> planner -- analyze auth

작업(task)이 없는 단계는 실행 모드(execution mode)로부터 동작을 상속받습니다. 체인(Chain) 단계는 이전 단계의 출력인 {previous}를 가져옵니다. 병렬(Parallel) 단계는 사용 가능한 첫 번째 작업을 폴백(fallback)으로 사용합니다.

/chain scout "analyze auth" -> planner -> worker
# scout는 "analyze auth"를 받습니다; planner는 scout의 출력을 받습니다; worker는 planner의 출력을 받습니다.

공유 작업(shared task)의 경우, 에이전트들을 나열하고 작업 앞에 --를 하나 배치하세요:

/chain scout planner -- analyze the auth system
/parallel scout reviewer -- check for security issues

에이전트 이름 뒤에 [key=value,...]를 추가하면 해당 단계의 기본값(defaults)을 재정의(override)할 수 있습니다:

/chain scout[output=context.md] "scan code" -> planner[reads=context.md] "analyze auth"
/run scout[model=anthropic/claude-sonnet-4] summarize this codebase
/parallel reviewer[skills=code-review+security] "review backend" -> reviewer[model=openai/gpt-5-mini] "review frontend"