Pi 코딩 에이전트 (Pi Coding Agent) 커스텀 인스턴스 모음입니다. 왜 만들었나요? 에이전트 코딩 (agentic coding) 시장의 선두주자인 Claude Code에 맞서 헤징(hedge)하는 것이 어떤 모습인지 보여주기 위해서입니다. 여기에서는 UI 커스터마이징, 에이전트 오케스트레이션 (agent orchestration) 도구, 안전성 감사 (safety auditing), 에이전트 간 오케스트레이션 (agent to agent orchestration), 그리고 교차 에이전트 통합 (cross-agent integrations) 방법을 보여줍니다.

6개 이상의 독특한 Pi 에이전트 하네스 (Pi Agent Harnesses)가 작동하는 모습을 보고 싶으신가요? 'Pi Coding Agent: The Only Claude Code Competitor' 영상을 시청하세요.

🆕

Pi-to-Pi 에이전트 간 통신 (agent-to-agent communication). 'Pi-to-Pi Communication' 섹션으로 이동하거나 'Pi to Pi: Two-Way Agent Orchestration' 영상을 시청하세요.

다음 세 가지가 모두 필요합니다:

도구	목적	설치
Bun ≥ 1.3.2	런타임 (Runtime) 및 패키지 매니저 (package manager)	bun.sh
just	태스크 러너 (Task runner)	brew install just
pi	Pi 코딩 에이전트 (Pi Coding Agent) CLI	Pi docs

Pi는 .env 파일을 자동으로 로드하지 않습니다 — API 키는 Pi를 실행하기 전에 쉘 (shell) 환경에 존재해야 합니다. 샘플 파일이 제공됩니다:

cp .env.sample .env # 템플릿 복사
# .env 파일을 열고 키를 입력하세요

.env.sample은 가장 인기 있는 4가지 제공업체를 지원합니다:

제공업체 (Provider)	변수	키 발급
OpenAI	OPENAI_API_KEY	platform.openai.com
Anthropic	ANTHROPIC_API_KEY	console.anthropic.com
Gemini	GEMINI_API_KEY	aistudio.google.com
OpenRouter	OPENROUTER_API_KEY	openrouter.ai
기타 다수	***	Pi Providers docs

워크플로우에 맞는 방식을 선택하세요:

옵션 A — 매 세션마다 수동으로 소싱 (Source manually):

source .env && pi

옵션 B — 한 줄 별칭 (One-liner alias) ( ~/.zshrc 또는 ~/.bashrc 에 추가):

alias pi='source $(pwd)/.env && pi'

옵션 C — just 태스크 러너 사용 (set dotenv-load를 통해 자동 연결):

just pi # 모든 just 레시피(recipe)에 대해 .env가 자동으로 로드됩니다
just ext-minimal # `pi`뿐만 아니라 모든 레시피에서 작동합니다

bun install

확장 기능 (Extension)	파일 (File)	설명 (Description)
pure-focus	extensions/pure-focus.ts	푸터 바 (footer bar)와 상태 표시줄 (status line)을 완전히 제거 — 순수하게 방해 없는 모드 (distraction-free mode)
minimal	extensions/minimal.ts	모델 이름과 10블록 컨텍스트 사용량 미터 [###-------] 30%를 보여주는 컴팩트한 푸터
cross-agent	extensions/cross-agent.ts	.claude/, .gemini/, .codex/ 디렉토리를 스캔하여 명령어, 기술 (skills), 에이전트 (agents)를 찾아 Pi에 등록
purpose-gate	extensions/purpose-gate.ts	시작 시 세션 의도 (session intent)를 선언하도록 요청; 지속적인 목적 위젯 (purpose widget)을 표시하고 답변 전까지 프롬프트 (prompts)를 차단
tool-counter	extensions/tool-counter.ts	풍부한 2줄 푸터: 1행에는 모델 + 컨텍스트 미터 + 토큰/비용 통계, 2행에는 현재 작업 디렉토리 (cwd)/브랜치 + 도구별 호출 횟수 표시
tool-counter-widget	extensions/tool-counter-widget.ts	에디터 상단에서 실시간으로 업데이트되며 배경색과 함께 도구별 호출 횟수를 보여주는 위젯
subagent-widget	extensions/subagent-widget.ts	백그라운드에서 Pi 서브 에이전트 (subagents)를 생성하는 /sub <task> 명령어; 각 서브 에이전트는 개별적인 스트리밍 실시간 진행 상황 위젯을 가짐
tilldone	extensions/tilldone.ts	작업 규율 시스템 (Task discipline system) — 작업 시작 전 태스크 (tasks)를 정의; 단계별 완료 상태를 추적; 푸터에 실시간 진행 상황과 함께 지속적인 태스크 목록 표시
agent-team	extensions/agent-team.ts	디스패처 전용 오케스트레이터 (Dispatcher-only orchestrator): 기본 에이전트가 dispatch_agent를 통해 모든 작업을 지정된 전문가 에이전트 (specialist agents)에게 위임; 그리드 대시보드 표시
system-select	extensions/system-select.ts	.pi/agents/, .claude/agents/, .gemini/agents/, .codex/agents/에 있는 에이전트 페르소나/시스템 프롬프트 (system prompts) 사이를 대화형으로 전환하는 /system 명령어
damage-control	extensions/damage-control.ts	실시간 안전 감사 (safety auditing) — 위험한 bash 패턴을 가로채고 .pi/damage-control-rules.yaml에 정의된 경로 기반 액세스 제어 (access controls)를 강제함
damage-control-continue	extensions/damage-control-continue.ts

damage-control과 동일한 규칙을 따르지만, 차단된 도구 호출 (tool calls) 시 중단하는 대신 실행 가능한 피드백을 반환합니다. 에이전트의 턴 (turn)이 계속 유지되며 적응할 수 있습니다. |
agent-chain |
extensions/agent-chain.ts |
순차적 파이프라인 오케스트레이터 (orchestrator) — 각 단계의 출력이 다음 단계의 프롬프트 (prompt)로 전달되는 다중 에이전트 체인; /chain을 사용하여 선택 및 실행 |
pi-pi |
extensions/pi-pi.ts |
문서화를 위해 병렬 연구 전문가 (research experts)를 사용하여 Pi 에이전트를 구축하는 메타 에이전트 (meta-agent) |
coms |
extensions/coms.ts |
Unix 소켓 (Unix sockets) / 명명된 파이프 (named pipes)를 통해 동일한 머신 상의 Pi 에이전트 간의 피어 투 피어 (P2P) 메시징. 도구: coms_list, coms_send, coms_get, coms_await |
coms-net |
extensions/coms-net.ts |
공유 HTTP/SSE 허브(scripts/coms-net-server.ts)를 통한 네트워크 기반 Pi-to-Pi. LAN 상의 서로 다른 머신 또는 원격 URL 뒤에서 작동. 도구: coms_net_* |
session-replay |
extensions/session-replay.ts |
세션 기록의 스크롤 가능한 타임라인 오버레이 - 커스터마이징 가능한 대화 UI를 보여줌 |
theme-cycler |
extensions/theme-cycler.ts |
키보드 단축키 (Ctrl+X/Ctrl+Q) 및 /theme 명령어를 사용하여 커스텀 테마 간 순환/전환 |

pi -e extensions/<name>.ts

확장 프로그램 (Extensions)은 조합 가능합니다 — 여러 개의 -e 플래그 (flags)를 전달하세요.

pi -e extensions/minimal.ts -e extensions/cross-agent.ts

just는 가장 유용한 조합들을 래핑 (wraps)합니다. 사용 가능한 모든 레시피 (recipes) 목록을 보려면 인자 없이 just를 실행하세요:

just

일반적인 레시피:

just pi # 확장 프로그램이 없는 순수 Pi
just ext-pure-focus # 집중 모드 (Distraction-free mode)
just ext-minimal # 최소한의 컨텍스트 미터 푸터 (context meter footer)
...

open 레시피를 사용하면 스택된 확장 프로그램의 임의의 조합으로 새로운 터미널 창을 띄울 수 있습니다 (.ts 생략):

just open purpose-gate minimal tool-counter-widget

pi-vs-cc/
├── extensions/ # Pi 확장 프로그램 소스 파일 (.ts) — 확장 프로그램당 파일 하나
├── specs/ # 확장 프로그램 기능 사양 (feature specifications)
...

Pi의 아키텍처 (architecture)는 여러 자율 에이전트 (autonomous agents)를 조정하기 쉽게 만듭니다. 이 플레이그라운드 (playground)에는 몇 가지 강력한 멀티 에이전트 확장 프로그램이 포함되어 있습니다:

subagent-widget 확장 프로그램을 사용하면 메인 터미널(terminal)에서 작업을 계속하는 동안 격리된 작업을 백그라운드 Pi 에이전트(agents)로 오프로드(offload)할 수 있습니다. /sub <task>를 입력하면 헤드리스(headless) 서브 에이전트가 생성되며, 이 에이전트는 에디터 상단의 지속적이고 실시간으로 업데이트되는 UI 위젯(widget)을 통해 스트리밍 진행 상황을 보고합니다.

agent-team 오케스트레이터(orchestrator)는 디스패처(dispatcher) 역할을 수행합니다. 기본 에이전트(primary agent)는 프롬프트(prompts)에 직접 답변하는 대신, 사용자의 요청을 검토하고 정의된 명단에서 전문가를 선택한 후 dispatch_agent 도구(tool)를 통해 작업을 위임합니다.

• 팀은 .pi/agents/teams.yaml에서 구성되며, 각 최상위 키는 에이전트 이름 목록을 포함하는 팀 이름입니다 (예: frontend: [planner, builder, bowser]).
• 개별 에이전트 페르소나(personas) (예: builder.md, reviewer.md)는 .pi/agents/에 위치합니다.
• pi-pi 메타 에이전트 (Meta-Agent): pi-pi 팀은 병렬 연구(parallel research)를 사용하여 고품질의 Pi 확장 프로그램을 구축하기 위해 .pi/agents/pi-pi/에 위치한 전문화된 Pi 프레임워크 전문가(ext-expert.md, theme-expert.md, tui-expert.md)에게 작업을 구체적으로 위임합니다.
• 웹 크롤링 폴백 (Web Crawling Fallbacks): 최신 프레임워크 문서를 동적으로 가져오기 위해, 이 전문가들은 기본 현대적 페이지 크롤러(page crawler)로 firecrawl을 사용하지만, Firecrawl이 실패하거나 사용할 수 없는 경우 bash 도구 세트에 내장된 네이티브 curl로 안전하게 폴백(fallback)하도록 명시적으로 프로그래밍되어 있습니다.

동적인 디스패처와 달리, agent-chain은 순차적 파이프라인 오케스트레이터(sequential pipeline orchestrator)로 작동합니다. 워크플로(workflows)는 .pi/agents/agent-chain.yaml에 정의되며, 여기서 한 에이전트의 출력이 다음 에이전트의 입력($INPUT)이 됩니다.

• 워크플로는 steps 목록으로 정의되며, 각 단계(step)는 agent와 prompt를 지정합니다.
• $INPUT 변수는 이전 단계의 출력(또는 첫 번째 단계의 경우 사용자의 초기 프롬프트)을 주입하며, $ORIGINAL은 항상 사용자의 초기 프롬프트를 포함합니다.
• 예시: plan-build-review 파이프라인은 사용자의 프롬프트를 planner에게 전달하고, 계획을 builder에게 전달하며, 마지막으로 코드를 reviewer에게 보냅니다.

하나의 Pi 코딩 에이전트보다 더 나은 것이 무엇일까요? 바로 두 개입니다. 서로 격리되어 나란히 놓인 두 개의 에이전트보다 더 나은 것이 무엇일까요? 바로 실제로 서로 대화하는 두 개의 에이전트입니다. 하위 에이전트 (Subagents), 디스패치 큐 (dispatch queues), 그리고 에이전트 체인 (agent chains)은 모두 하나의 형태를 공유합니다. 즉, 정보가 계층 구조를 따라 한 방향으로 흐른다는 점입니다. coms와 coms-net은 누락된 패턴, 즉 동일한 머신 내에서 혹은 네트워크를 통해 피어 투 피어 (peer-to-peer)로 대화하는 두 개의 동등한 Pi 에이전트를 추가합니다. 오케스트레이터 (orchestrator)도, 부모/자식 관계도 없으며, 작업이 계층을 통과할 때 정보 손실도 발생하지 않습니다. 어떤 에이전트가 아이디어를 냈는지와 상관없이 가장 좋은 아이디어가 승리합니다.

이것이 바로 변화입니다. 하위 에이전트 위임 (Sub-agent delegation)과 메시지 큐 (message queues)는 강력한 패턴이지만, 이들은 기본적으로 정보를 한 방향으로만 이동시킵니다. 결과가 돌아올 때조차 그것은 하향식 (top-down)의 단방향 스트림입니다. 피어 투 피어 (peer-to-peer)는 이를 뒤집습니다. 부모와 자식이 아닌 동등한 에이전트 사이에서 프롬프트(prompt) → 응답(response) → 프롬프트(prompt) → 응답(response)의 과정을 거칩니다. 이는 기본적으로 양방향 정보 흐름을 가능하게 합니다.

실무에서 이것이 중요한 이유:

기기 간 작업 (Cross-device work). 한쪽 박스에는 프로덕션 에이전트 (production agent)를, 사용자의 노트북에는 개발 에이전트 (dev agent)를 둡니다. 프로덕션 측은 개인정보 (PII)를 비식별화(redacted)하면서도 개발 측의 질문에 답변할 수 있습니다. 즉, 데이터 유출 없이 실제 엔지니어링 작업을 수행할 수 있습니다.

이질적인 팀 (Heterogeneous teams). 동일한 풀(pool) 내에서 claude-opus-4-7, gpt-5.5, deepseek를 실행합니다. 각 모델은 서로 다른 강화학습 (RL) 훈련을 거쳤으며, 이들이 함께하면 개별 모델이 놓치는 부분을 잡아낼 수 있습니다.

집중된 컨텍스트 창 (Focused context windows). 모든 문제를 다루느라 비대해진 하나의 에이전트 대신, 각 에이전트는 자신의 영역에 특화된 상태를 유지합니다. 집중된 에이전트가 성능이 뛰어난 에이전트입니다. 관련 없는 문제들을 하나의 컨텍스트 창 (context window)에 많이 집어넣을수록 오류율은 높아집니다.

평면적 구성 (Flat composition). 이것은 여전히 에이전트 + 확장 기능 (extension) 구조입니다. 하향식 구조가 필요할 때는 이를 다시 오케스트레이터 패턴으로 구성할 수 있고, 필요하지 않을 때는 평면적인 상태를 유지할 수 있습니다.

이 패턴이 중요한 더 깊은 이유는 다음과 같습니다: 가장 가치 있는 정보는 거의 항상 워커 (worker) 레벨에 존재한다는 점입니다. 하지만 계층 구조에서는 이 정보가 의사결정을 형성하기까지 여러 계층을 거쳐 올라가야 하며 (그리고 여러 번의 재작성 과정을 견뎌야 합니다), 평면적인 구조 (Flat structures)는 가치 있는 정보가 그 자체의 장점만으로 승리할 수 있게 해줍니다. 에이전트 시스템에서도 동일한 역학이 작용합니다. 아티팩트 (artifact, 즉 프로덕션 데이터베이스, 실행 중인 테스트, 라이브 파일 등)에 가장 가까운 에이전트가 대개 가장 날카로운 시야를 가집니다. 모든 신호를 오케스트레이터 (orchestrator)를 통해 라우팅하는 대신, 에이전트가 동료들에게 직접 말할 수 있게 함으로써 그 신호의 온전함을 유지할 수 있습니다.

구분	coms (로컬)	coms-net (네트워크형)
전송 (Transport)	Unix 소켓 / Windows 명명된 파이프 (named pipes)	HTTP + 서버 전송 이벤트 (Server-Sent Events)
범위 (Scope)	단일 머신	동일 머신, LAN, 또는 원격 URL
탐색 (Discovery)	~/.pi/coms/projects/<project>/agents/*.json에 있는 파일 레지스트리	~/.pi/coms-net/projects/<project>/server.json에 있는 공유 허브
서버 (Server)	없음 — 에이전트가 직접 리스닝	bun scripts/coms-net-server.ts (Bun HTTP 허브)
도구 (Tools)	coms_list, coms_send, coms_get, coms_await	coms_net_list, coms_net_send, coms_net_get, coms_net_await
위젯 (Widget)	에디터 상단의 라이브 풀 (Live pool)	에디터 상단의 라이브 풀 (Live pool)
인증 (Auth)	~/.pi/coms/에 대한 OS 파일 권한	PI_COMS_NET_AUTH_TOKEN (localhost용 자동 생성, LAN/원격용 필수)

전체 노출 영역은 네 가지 도구로 구성됩니다. 네트워크상의 에이전트를 나열하고, 프롬프트를 보내고, 응답이 도착할 때까지 폴링 (polling, 비차단 방식)하거나 차단 (blocking)하면 됩니다. 그게 전부입니다.

도구	기능
*_list	풀 내의 피어 (peer) 에이전트를 이름, 모델, 실시간 컨텍스트 윈도우 (context-window) 사용량과 함께 나열
*_send	피어에게 프롬프트 전송; 수신자가 확인 응답 (ack)을 보내면 msg_id 반환
*_get	msg_id에 대한 비차단 폴링 — pending / complete / error
*_await	답장이 도착하거나 타임아웃이 발생할 때까지 차단 (PI_COMS_*_TIMEOUT_MS를 통해 기본 30분 설정)

답장은 동일한 채널을 통해 다시 전달됩니다. 인바운드 프롬프트 (inbound prompt)가 턴 (turn)을 트리거하면, 수신자의 최종 어시스턴트 메시지 (assistant message)가 자동으로 응답으로 패키징됩니다. 때로는 발사 후 망각 (fire-and-forget, Slack 스타일의 상태 핑) 방식을 원할 수도 있고, 때로는 답변을 기다리고 싶을 수도 있으며 (*_await), 때로는 계속 작업을 진행하다가 나중에 확인하고 싶을 수도 있습니다 (*_get). 이 세 가지 스타일 모두 동일한 네 가지 프리미티브 (primitives)에서 파생됩니다.

# Terminal 1
just local-coms --name planner --purpose "Plans the work" --color "#36F9F6"
# Terminal 2
...

각 에이전트는 다른 에이전트들의 라이브 풀 위젯 (live pool widget)을 보여줍니다. 어느 쪽에서든 에이전트는 target: "planner" (또는 `