# @tintinweb/pi-subagents

English · 简体中文 · 日本語 · 한국어

> 이 문서는 영어 README의 일부만 번역한 것입니다(기계 번역, 오류 제보 환영). 소개, 기능, 설치, 빠른 시작, `/agents` 명령어만 담고 있습니다. UI, 사용자 정의 에이전트, 도구 매개변수, 설정과 기본값, 이벤트, RPC 등 나머지 내용은 영어로만 제공됩니다: [영어 README 전체](README.md). > > *Partial translation of the English README. Full reference: [README.md](README.md) · https://github.com/tintinweb/pi-subagents/blob/master/README.md*

@tintinweb/pi-subagents

npm 버전 npm 다운로드 수 CI 라이선스: MIT

pi >= 1.1.0 필요 pi.dev 패키지 Claude Code 호환 마지막 커밋

pi를 위한 Claude Code 스타일의 서브에이전트와 워크플로 오케스트레이션.

설치 · 빠른 시작 · UI (EN) · 사용자 정의 에이전트 (EN) · 도구 (EN) · 설정 (EN) · 워크플로 (EN) · 변경 이력 (EN)

pi install npm:@tintinweb/pi-subagents

pi에 **Claude Code 스타일의 자율 서브에이전트와 워크플로 오케스트레이션**을 제공하는 [pi](https://pi.dev) 확장입니다. 독립된 세션에서 동작하는 전문 에이전트를 실행할 수 있으며, 각 에이전트는 자체 도구, 시스템 프롬프트, 모델, 사고 수준을 가집니다. 에이전트를 백그라운드에서 실행하거나(기본값) 완료될 때까지 기다릴 수 있고, 실행 중에 스티어링하거나, 완료된 세션을 재개하거나, 직접 에이전트 타입을 정의할 수 있습니다. 오케스트레이션을 즉흥적으로 진행하면 안 되는 경우에는 결정론적인 JavaScript 스크립트를 `SubagentWorkflow` 도구에 넘기면 됩니다(`agent()`, `parallel()`, `pipeline()`). Claude Code의 `Workflow` 도구용으로 작성한 스크립트는 몇 가지 [차이점](https://github.com/tintinweb/pi-subagents/blob/master/docs/workflows.md#coming-from-claude-code)을 제외하면 여기서도 실행됩니다. pi-subagents 스크린샷 https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543 pi-color-badges-white ## 기능 - **Claude Code와 같은 룩앤필**: 도구 이름, 호출 규칙, UI 패턴(`Agent`, `get_subagent_result`, `steer_subagent`)이 같아서 네이티브 기능처럼 느껴집니다 - **병렬 백그라운드 에이전트**: 여러 에이전트를 동시에 실행하며, 한도를 넘는 에이전트는 자동으로 대기열에 넣습니다(동시 실행 한도는 설정 가능, 기본값 10). 완료 알림은 부모 에이전트의 다음 경계 시점에 도착하며, 여러 에이전트가 함께 완료되면 알림도 한꺼번에 도착합니다 - **실시간 위젯 UI**: 편집기 위에 상주하는 위젯으로, 애니메이션 스피너, 실시간 도구 활동, 토큰 수, 색상 상태 아이콘을 보여 줍니다. `/agents → Settings → Widget`에서 설정합니다: `all`(모든 에이전트), `background`(기본값, 포그라운드 실행은 이미 `Agent` 도구 결과로 인라인 표시되므로 숨김), `off` - **FleetView**: 편집기 아래에 표시되는 Claude Code 스타일의 탐색 가능한 목록으로, `main`과 실행 중인 모든 서브에이전트가 나옵니다(먼저 실행된 순). 빈 프롬프트에서 `↓`(또는 `←`)를 눌러 목록으로 들어가고, `↑`/`↓`로 선택을 옮기고, `Enter`로 선택한 에이전트의 대화를 실시간 자동 갱신 상태로 열고, `Esc`로 돌아옵니다. 완료된 에이전트는 잠시 남아 있다가 사라지며, 뷰어는 완료 후에도 열려 있으므로 최종 출력을 읽을 수 있습니다. `/agents → Settings → Fleet view`에서 켜고 끕니다 - **대화 뷰어**: `/agents`에서 아무 에이전트나 선택하면 전체 대화를 실시간으로 스크롤해 보여 주는 오버레이가 열립니다(새 내용을 자동으로 따라가며, 위로 스크롤하면 일시 정지). pi의 전체 화면 모드에서는 테두리 없이 터미널 전체를 쓰는, 마우스를 지원하는 관찰 화면이 됩니다. `Enter`로 입력창을 열고 내용을 입력한 뒤 `Enter`로 보내면 실행 중인 에이전트를 그 자리에서 스티어링할 수 있습니다(`Esc` 또는 빈 내용 제출 시 돌아감). 메시지는 사용자 메시지로 표시되며, 에이전트가 현재 도구 실행을 마친 뒤 방향을 바꿉니다. 실행 중인 포그라운드 `Agent` 호출에서 `b`를 누르면 그 실행을 백그라운드로 넘깁니다([포그라운드 에이전트를 백그라운드로 보내기](#포그라운드-에이전트를-백그라운드로-보내기) 참고). 아직 실행 중인 에이전트는 `x`를 누르면(확인을 위해 `x`를 한 번 더) 중지됩니다. 스티어링과 중지는 백그라운드 에이전트에도 동작합니다. 도구 호출은 에이전트 세션에 등록된 렌더러를 통해 pi 자체 트랜스크립트와 같은 방식으로 표시됩니다: bash 호출은 명령과 출력, `read`는 줄 번호, `edit`는 diff, 확장 도구는 자체 렌더러로 표시되고, 렌더러가 없는 도구는 인자와, 길이가 제한된 출력 미리보기로 대체됩니다. `ctrl+o`(또는 `app.tools.expand`에 지정된 키)로 생략된 도구 출력을 펼칩니다. 어시스턴트 텍스트는 Markdown으로 렌더링되며, `m`을 누르면 끄기, 어시스턴트만, 전체 순으로 전환됩니다([Viewer markdown](README.md#persistent-settings) 참고) - **사용자 정의 에이전트 타입**: `.pi/agents/.md` 또는 `.agents/agents/.md`(프로젝트), 혹은 전역 위치에 에이전트를 정의합니다. YAML frontmatter로 시스템 프롬프트, 모델 선택, 사고 수준, 도구 제한, Claude Code 호환 색상 이름 배지를 지정합니다 - **패키지에 포함된 에이전트**: pi 패키지는 `package.json`에 `"pi": { "subagents": { "agents": ["./agents"] } }`를 넣어 자체 서브에이전트와 워크플로 스크립트를 선언할 수 있으므로, `pi install`만으로 설정이 끝납니다. 머신마다 또는 컨테이너가 시작될 때마다 `.pi/agents/`로 파일을 복사할 필요가 없습니다. pi가 실제로 설치한 패키지만 읽으며(`node_modules`는 절대 읽지 않음), 패키지 정의는 직접 작성한 어떤 에이전트보다도 우선순위가 낮고, `/agents`에서는 읽기 전용으로 표시되며 Eject와 Disable을 쓸 수 있습니다. `packageAgents` / `packageWorkflows`로 범위를 좁히거나 끌 수 있습니다. **[전체 가이드](https://github.com/tintinweb/pi-subagents/blob/master/docs/packages.md)** - **중첩 서브에이전트**: 내장 `general-purpose` 에이전트는 Claude Code와 마찬가지로 자신의 서브에이전트에게 작업을 위임할 수 있습니다. `Explore`와 `Plan`은 위임할 수 없고, 사용자 정의 에이전트는 `allowed_subagents`를 설정하면 켜집니다. 위임하는 에이전트는 소유 범위로 제한된 자체 `Agent`, `get_subagent_result`, `steer_subagent` 도구를 얻으며, 메인 세션 기준 중첩 깊이에 상한이 있습니다(기본값 2). 자기 자식 에이전트만 제어할 수 있고, 자신이 끝나면 자식 에이전트는 중지되며, 자식의 트랜스크립트와 토큰 사용량은 부모에게 합산됩니다. 이 허용 목록은 권한 경계입니다. 자식은 자신의 도구로 실행되므로, 이 목록은 `tools:` 자체만큼 신중하게 고르세요 - **에이전트 멘션**: 서브에이전트를 일급 대상으로 다룹니다. 프롬프트에 `@explore also check the RPC path`를 입력하면 메인 모델 대신 해당 에이전트에 전달되며, 채팅에는 한 글자도 들어가지 않습니다. 하나의 문법으로 전체 생명 주기를 다룹니다: 실행 중일 때 메시지 보내기, 완료된 뒤 재개하기, 한참 뒤에 디스크에서 세션 다시 열기, 한 번도 실행된 적이 없으면 시작하기. 실행 중이 아닌 에이전트를 멘션하면 화면 밖에서 복제한 대화를 통해 실행되므로, Claude Code처럼 컨텍스트를 바탕으로 작성된 프롬프트와 실제 `Agent` 도구 호출을 얻으면서도 채팅에는 한 글자도 들어가지 않습니다. `direct` 모드는 모델을 전혀 호출하지 않고 입력한 텍스트로 그 자리에서 바로 시작합니다. 오케스트레이터가 에이전트에 `name`을 붙이면 `@auth-audit`처럼 부를 수 있고, 이 이름은 `steer_subagent`/`get_subagent_result`에서도 쓸 수 있습니다. `@`은 pi의 파일 자동 완성과 함께 실행 중인 에이전트, 재개 가능한 에이전트, 시작 가능한 타입을 자동 완성합니다. `@main`은 텍스트를 강제로 메인 모델로 보냅니다. `/agents → Settings → Agent mentions`에서 켜고 끕니다 - **스크립트 워크플로**: `SubagentWorkflow` 도구는 여러 서브에이전트를 오케스트레이션하는 결정론적인 JavaScript 스크립트를 실행합니다: `agent()`, `parallel()`, `pipeline()`, `phase()`, `log()`, `args`를 사용하고, 순수 리터럴 `meta` 블록으로 단계(phase)를 선언합니다. `pipeline()`은 스테이지 사이에 배리어가 없으므로, 한 항목이 뒤쪽 스테이지에 있는 동안 다른 항목은 아직 첫 스테이지에 있을 수 있습니다. 반면 `parallel()`은 가장 느린 에이전트가 끝날 때까지 빠른 에이전트를 모두 놀게 합니다. 워크플로는 실시간 카드와 함께 백그라운드에서 실행되며, `/agents → Workflows` 또는 FleetView에서 해당 실행을 선택해 살펴볼 수 있습니다. `agent()`는 `gate: "npm test"`도 받아, 다른 모델에 묻는 대신 명령을 실행해(격리된 경우 해당 worktree 안에서) 자식을 검증합니다. `resume: "