nicobailon/pi-subagents

Pi extension for async subagent delegation with truncation, artifacts, and session sharing

pi‑subagents란 무엇인가?

pi‑subagents는 Pi AI 어시스턴트 플랫폼의 확장 프로그램으로, 단일 Pi 세션이 포커스된 하위 에이전트(subagents라고 함)를 생성하여 특정 작업을 처리할 수 있게 합니다. AI "어시스턴트"에게 전문가 팀을 제공한다고 생각하면 됩니다. 포그라운드 또는 백그라운드에서 실행하고, 결과를 보고하고, 자연어 명령으로 오케스트레이션할 수 있습니다.

핵심 아이디어

부모 세션(Pi) 이 대화를 제어합니다.
하위 에이전트를 요청하면(예: "reviewer를 사용하여 이 diff를 리뷰해 줘"), Pi는 전용 역할을 가진 자식 Pi 세션을 시작합니다.
자식은 작업(코드 리뷰, 리서치, 구현 등)을 수행하고 결과를 부모에게 반환합니다.
자식은 인라인(포그라운드)으로 실행되어 출력을 채팅에 직접 스트리밍하거나, 분리(백그라운드)로 실행되어 메인 대화로 돌아온 후에도 계속 실행될 수 있습니다.

내장 에이전트(즉시 사용 가능)

에이전트	일반적인 용도
scout	코드베이스를 빠르게 매핑: 관련 파일, 진입점, 데이터 흐름, 위험 요소 나열.
researcher	웹이나 문서에서 정보를 가져오고, 출처를 인용하고, 간결한 브리프를 생성.
evidence‑auditor	리서치 주장이 실제로 인용된 출처에 의해 뒷받침되는지 검증.
worker	구현 수행: 파일 편집, 검증 실행, 추측하기 전에 승인 요청.
reviewer	코드 리뷰 – 정확성, 테스트 커버리지, 엣지 케이스, 단순성 확인; 선택적으로 작은 수정 적용.
oracle	계획에 대한 제2의 의견 제공, 가정에 도전, 맹점 지적(파일 편집 없음).
delegate	부모 세션과 유사하게 동작하는 경량 범용 헬퍼.

상호 작용 방법

구성 파일을 작성하거나 특별한 슬래시 명령을 배울 필요가 없습니다. 패키지를 설치한 후:

pi install npm:pi-subagents

자연어로 Pi에게 요청하기만 하면 됩니다. 예:

Use reviewer to review this diff.
Ask oracle for a second opinion on my current plan.
Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity. Pi가 어떤 하위 에이전트를 시작할지, 포그라운드 또는 백그라운드에서 실행할지, 결과를 어떻게 구성할지 결정합니다.

일반적인 워크플로우

목표	자연어 프롬프트
제2의 의견 얻기	`Ask oracle to review this plan and challenge assumptions.`
어려운 버그 해결	`Use oracle to investigate this bug before we edit.`
풀 리퀘스트 diff 리뷰	`Use reviewer to review this diff.`
여러 리뷰어를 동시에 실행	`Run reviewers for correctness, tests, and cleanup.`
여러 고문 간 토론 진행	`Use /council with model‑based advisors to compare this decision.`
구현 후 검증	`Implement this, then review it.`
지속적인 리뷰 루프	`Run a review loop on this change with a max of 3 rounds.`
백그라운드 실행	`Run this in the background.`
실행 중인 작업 검사	`Show me the current async runs.`

확장 프로그램에는 이러한 패턴을 반복적으로 사용할 수 있도록 /parallel‑review 및 /review‑loop와 같은 단축 명령도 포함되어 있습니다.

관찰 가능성 및 제어

포그라운드 실행 은 채팅에서 라이브로 스트리밍됩니다.
백그라운드 실행 은 편집기 아래의 지속적인 FleetView 패널에 나타납니다. /subagents‑fleet로 라이브 인스펙터를 열어 자식을 탐색하고, 대화 내용을 읽고, 안내하거나 중지할 수 있습니다.
내장 워치독은 적대적 변경을 모니터링하고, LSP 검사를 강제하고, 단일 실행이 생성할 수 있는 하위 에이전트 수를 제한할 수 있습니다(maxSubagentSpawnsPerRun, 기본값 64).
헬퍼 명령:
- /subagents‑doctor – 하위 에이전트 시스템에 대한 상태 점검 실행.
- /subagents‑guide [topic] – workflows, agents, observability 등 주제에 대한 문서 표시.

구성

모든 설정은 config.json(또는 환경 변수)에 있습니다. 중요한 설정 항목은 다음과 같습니다:

toolActivation – subagent 도구를 즉시 로드할지, 모델의 프롬프트 캐시가 새로 고쳐진 후에만 로드할지 제어.
bg_wait – 부모가 상태를 보고하기 전에 백그라운드 자식을 기다리는 시간.
maxSubagentSpawnsPerRun – 단일 오케스트레이션이 생성할 수 있는 총 논리적 자식 수를 제한.

자세한 내용은 저장소의 docs/ 폴더에 있습니다.

누가 혜택을 받을 수 있나요?

개발자 편집기를 떠나지 않고 AI 지원 코드 리뷰, 자동화된 구현 또는 리서치를 원하는 사람.
팀 재현 가능하고 감사 가능한 AI 워크플로우가 필요한 팀(예: "리뷰어 실행, 그 다음 워커 실행, 또 다른 리뷰어 실행").
Pi 플랫폼의 파워 유저 여러 전문 AI 에이전트를 단일 일관된 파이프라인으로 구성하려는 사람.

빠른 시작 체크리스트

확장 프로그램 설치: pi install npm:pi-subagents.
Pi 채팅에서 Use reviewer to review this diff.와 같은 자연어 요청을 입력.
대화에서 결과가 스트리밍되는 것을 보거나 백그라운드 플릿 뷰를 검사.
/subagents‑guide를 사용하여 고급 워크플로우 및 구성 옵션을 탐색.

결론: pi‑subagents는 단일 Pi AI 어시스턴트를 목적에 맞게 구축된 에이전트의 작은 오케스트레이션 팀으로 전환하여 코드 리뷰, 리서치, 구현, 감사와 같은 복잡한 작업을 실행, 모니터링, 반복하기 쉽게 만듭니다.