Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Pi 코딩 에이전트가 TUI 오버레이를 통해 대화형 CLI를 자율적으로 실행할 수 있게 해주는 확장 기능입니다. 사용자는 에이전트의 작업을 실시간으로 관찰하거나 직접 제어권을 가져올 수 있으며, 에디터, REPL, 데이터베이스 쉘 등 다양한 도구를 지원합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Coding Assistants의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Pi 코딩 에이전트 (coding agent)를 위한 확장 기능으로, Pi가 관찰 가능한 TUI (Text User Interface) 오버레이에서 대화형 CLI (Command Line Interface)를 자율적으로 실행할 수 있게 해줍니다. 사용자가 지켜보는 동안 Pi가 서브프로세스 (subprocess)를 제어하며, 사용자는 언제든 제어권을 가져올 수 있습니다.
interactive_shell({ command: 'vim config.yaml' })
중요: 이 README에 포함된 interactive_shell({...}) 스니펫 (snippets)은 Pi(또는 확장 기능/프롬프트 작성자)가 수행하는 도구 호출 (tool calls)입니다. 최종 사용자가 이를 채팅창에 직접 입력하지 않습니다. 사용자는 Pi에게 무언가를 실행하도록 요청하거나 (예: "dispatch 모드로 실행해줘"), /spawn, /attach, /dismiss 명령어를 사용하십시오.
일부 작업에는 에디터 (editors), REPL (Read-Eval-Print Loop), 데이터베이스 쉘 (database shells), 장시간 실행되는 프로세스 (long-running processes)와 같은 대화형 CLI가 필요합니다. Pi는 다음과 같은 오버레이에서 이를 실행할 수 있습니다:
사용자 관찰 (User watches) - 실시간으로 정확히 무엇이 일어나고 있는지 확인
사용자 제어 (User takes over) - 무엇이든 입력하여 제어권을 획득
에이전트 모니터링 (Agent monitors) - 상태를 쿼리 (query)하고, 입력을 보내며, 종료 시점을 결정
다음과 같은 모든 CLI와 함께 작동합니다: vim, htop, psql, ssh, docker logs -f, npm run dev, git rebase -i 등.
pi install npm:pi-interactive-shell
interactive-shell 기술 (skill)은 자동으로 ~/.pi/agent/skills/interactive-shell/에 심볼릭 링크 (symlinked)됩니다.
요구 사항: Node.js. PTY (Pseudo-Terminal) 지원은 zigpty 사전 빌드된 바이너리 (prebuilt binaries)를 사용합니다 (지원되는 플랫폼에서는 node-gyp 툴체인 (toolchain)이 필요하지 않음).
| 모드 (Mode) | 에이전트 대기 여부? | 출력이 에이전트에 도달하는 방식 | 적합한 용도 |
|---|---|---|---|
| Interactive (기본값) | 예 — 종료될 때까지 차단 (blocks) | 도구 반환 값 (Tool return value) | 에디터, REPL, SSH — 즉시 결과가 필요한 경우 |
| Hands-free | 아니요 | sessionId로 폴링 (Poll) | 개발 서버, 빌드 — 진행 상황을 지켜보고 후속 명령을 보내고 싶은 경우 |
| Dispatch | 아니요 | triggerTurn을 통한 완료 알림 | 서브에이전트 (subagents)에게 작업 위임 — 실행 후 망각 (fire and forget) |
| Monitor | 아니요 | 구조화된 모니터 트리거 이벤트에 대한 알림 | 와처 (Watchers), 로그, 테스트 및 상태 확인 — 특정 상황이 발생했을 때만 깨어남 |
Interactive — 오버레이가 열리고, 사용자가 세션을 제어하며, 에이전트는 세션이 닫힐 때까지 기다립니다. 에디터(vim) 등에 사용하십시오.
), 데이터베이스 쉘 (psql)
), 또는 에이전트가 최종 결과를 즉시 받아야 하는 모든 작업에 적합합니다.
Hands-free — 오버레이가 열리지만 즉시 닫힙니다. 에이전트는 sessionId를 사용하여 주기적으로 폴링 (polling)하며 상태를 확인하고 새로운 출력을 가져옵니다. 실행 도중 반응(입력 전송, 로그 확인, 완료 시 종료 등)이 필요한 장시간 실행되는 빌드 또는 개발 서버에 유용합니다.
Dispatch — 즉시 반환됩니다. 폴링 (polling)은 없습니다. 에이전트는 세션이 완료될 때(자연 종료, 타임아웃, 정적 상태 감지 또는 사용자 종료)에만 triggerTurn을 통해 깨어납니다. 알림에는 출력의 마지막 부분(tail)이 포함됩니다. 이는 서브 에이전트 (subagents)에게 작업을 위임할 때 사용하는 기본값입니다. 오버레이를 완전히 건너뛰려면 background: true를 추가하십시오.
Monitor — 즉시 반환됩니다. 폴링 (polling)도, 완료 알림도 없습니다. 에이전트는 설정된 모니터 트리거 (monitor trigger)가 이벤트를 발생시킬 때 깨어납니다. 스트림 트리거 (stream triggers), 폴링 차이 체크 (poll-diff checks), 퍼스트 클래스 파일 와칭 (first-class file watching), 선택적 쿨다운 (cooldowns), 지속성 제어 (persistence controls), 탐지 명령 (detector commands) 및 이벤트 이력 쿼리 (event history queries)를 지원합니다. 헤드리스 (headless)로 실행되며, 필요한 경우 검사를 위해 연결(attach)할 수 있습니다.
아래 예시는 에이전트 측의 도구 호출 (tool calls)을 보여줍니다. 이는 최종 사용자를 위한 채팅 명령이 아닙니다.
Pi, Codex, Claude 및 Cursor의 경우, 에이전트는 명령 문자열을 수동으로 만드는 대신 구조화된 스폰 파라미터 (structured spawn params)를 사용할 수 있습니다:
// 사용자: "파일을 대화형으로 편집할 수 있도록 pi를 스폰(spawn)해줘"
interactive_shell({ spawn: { agent: "pi" }, mode: "interactive" })
// 사용자: "이 리팩토링 작업을 codex에게 위임하고 완료되면 알려줘"
...
구조화된 spawn은 사용자용 /spawn 명령과 동일한 리졸버 (resolver) 및 설정 기본값을 사용합니다. 임의의 CLI 및 사용자 정의 실행 문자열을 위해 원시 command 방식도 여전히 지원됩니다.
Codex의 이미지 또는 디자인 작업의 경우, Codex는 프롬프트에서 직접 gpt-image-2를 호출할 수 있습니다. 일반적으로 자연어만으로도 충분하며, 필요한 경우 $imagegen을 사용하여 이미지 생성 도구를 강제할 수 있습니다. 편집 및 반복 작업을 위해 -i를 사용하여 참조를 첨부하십시오. 번들로 포함된 codex-cli를 참조하십시오.
구체적인 예시를 위한 skill입니다. Cursor CLI 전용 명령 참조를 보려면 선택 사항인 examples/skills/cursor-cli skill을 확인하십시오. Cursor의 structured spawn은 --model composer-2-fast를 기본값으로 설정하며, 이는 Cursor의 Composer 2 Fast 모델을 명시적으로 선택합니다.
// 사용자가 말함: "vim으로 package.json을 여세요"
interactive_shell({ command: 'vim package.json' })
// 사용자가 말함: "postgres 데이터베이스에 연결하세요"
...
오버레이(overlay)가 닫힐 때까지 에이전트(agent)의 턴은 차단됩니다. 사용자가 세션을 직접 제어합니다.
// 장기 실행 프로세스 시작
interactive_shell({
command: 'npm run dev',
...
사용자가 지켜볼 수 있도록 오버레이가 열립니다. 에이전트는 주기적으로 체크인(check in)합니다. 사용자는 무엇이든 입력하여 제어권을 가져올 수 있습니다. 모니터링 중인 hands-free 또는 dispatch 세션의 제어권을 가져온 후에는 Ctrl+G를 눌러 에이전트에게 제어권을 돌려주십시오.
// 사용자가 말함: "auth 모듈 리팩토링을 pi에게 위임하고 완료되면 나에게 알려줘"
interactive_shell({
command: 'pi "Refactor the auth module"',
...
세션이 완료되면 에이전트는 새로운 턴에서 간결한 알림을 받습니다:
Session calm-reef completed successfully (5m 23s). 847 lines of output.
Step 9 of 10
Step 10 of 10
...
알림에는 짧은 꼬리 부분(마지막 5줄)과 재연결(reattach) 지침이 포함됩니다. PTY는 5분 동안 보존되므로 에이전트가 전체 스크롤백(scrollback)을 검토하기 위해 연결할 수 있습니다.
Dispatch는 autoExitOnQuiet: true를 기본값으로 사용합니다. 즉, 세션에 15초의 시작 유예 기간(startup grace period)이 주어지며, 그 후 출력이 조용해지면(기본값 8초) 종료됩니다. 이는 작업 지향적 서브 에이전트(subagents)에게 완료 신호를 보냅니다. handsFree: { gracePeriod: 60000 }를 사용하여 유예 기간을 조정하거나, handsFree: { autoExitOnQuiet: false }를 사용하여 이 기능을 완전히 제외할 수 있습니다.
오버레이는 여전히 사용자에게 표시되며, 사용자는 Ctrl+T로 출력을 전송하거나, Ctrl+B로 백그라운드로 보내거나, 직접 타이핑하여 제어권을 가져오거나, Ctrl+Q로 더 많은 옵션을 선택할 수 있습니다. Ctrl+G는 사용자가 모니터링 중인 hands-free 또는 dispatch 세션의 제어권을 가져온 후에만 의미가 있습니다.
// 오버레이 없음 — 완전히 보이지 않게 실행됨
interactive_shell({
command: 'pi "Fix all lint errors"',
...
단일 인터랙티브 오버레이 (interactive overlay)와 함께 여러 개의 헤드리스 디스패치 (headless dispatches)를 동시에 실행할 수 있습니다. 이것이 서브에이전트 (subagent) 작업을 병렬화하는 방법입니다. 즉, 세 개의 백그라운드 디스패치를 실행하고 각 완료 알림 (completion notification)이 도착할 때마다 결과를 처리하는 방식입니다.
이 예시들은 **에이전트 도구 호출 (agent tool calls)**입니다. 최종 사용자는 자연어(예: "내 테스트를 감시하고 실패 시 알려줘")로 요청해야 하며, Pi는 모니터 설정 (monitor config)과 함께 interactive_shell을 호출해야 합니다.
모니터 트리거 (monitor triggers)가 이벤트를 방출할 때 에이전트를 깨우십시오. 폴링 (polling)이나 프로세스 완료를 기다릴 필요가 없습니다.
// 사용자가 말함: "내 테스트를 감시하고 실패나 에러가 발생하면 알려줘"
interactive_shell({
command: 'npm test --watch',
...
모니터 모드 (Monitor mode)는 구조화된 페이로드 (structured payloads) (sessionId, eventId, timestamp, strategy, triggerId, matchedText, lineOrDiff, stream)를 방출하며, 이제 모니터가 중단될 때 (스트림 종료, 스크립트 실패, 중단 또는 타임아웃) 라이프사이클 알림 (lifecycle notifications)도 방출합니다. 구조화된 monitor 객체를 사용하는 방향으로 개선되면서 monitorFilter는 제거되었습니다.
interactive_shell({ monitorStatus: true, monitorSessionId: "calm-reef" })
interactive_shell({ monitorEvents: true, monitorSessionId: "calm-reef" })
interactive_shell({ monitorEvents: true, monitorSessionId: "calm-reef", monitorSinceEventId: 42 })
...
모니터 세션 (Monitor sessions)은 헤드리스 (headless)로 실행되며 다른 백그라운드 세션(listBackground, /attach, dismissBackground)과 같이 관리할 수 있습니다.
깔끔하게 종료되지 않는 TUI 앱의 출력을 캡처하십시오:
interactive_shell({
command: "htop",
mode: "hands-free",
...
실행 후 잊어버리는 방식 (fire-and-forget)의 단일 작업 위임의 경우, 출력이 8초 동안 없을 때 세션을 종료하도록 자동 종료 (auto-exit)를 활성화하십시오:
interactive_shell({
command: 'pi "Fix the bug in auth.ts"',
mode: "hands-free",
...
15초의 시작 유예 기간 (startup grace period)은 서브프로세스 (subprocess)가 출력을 생성할 시간을 갖기 전에 세션이 종료되는 것을 방지합니다. gracePeriod를 통해 호출마다 이를 커스텀할 수 있습니다.
:
interactive_shell({
command: 'pi "Run the full test suite"',
mode: "hands-free",
...
기본 유예 기간은 설정 파일의 autoExitGracePeriod를 통해 전역적으로도 구성할 수 있습니다.
상호 주고받는 상호작용이 필요한 멀티 턴 (multi-turn) 세션의 경우, 이를 비활성화된 상태(기본값)로 두고 작업이 완료되었을 때 kill: true를 사용하세요.
// 텍스트 전용 (텍스트를 입력하지만 제출하지는 않음)
interactive_shell({ sessionId: "calm-reef", input: "SELECT * FROM users;" })
// 텍스트를 입력하고 Enter를 누름
...
pi와 같은 에디터 기반 TUI (Text User Interface)의 경우, 원시 input은 텍스트만 입력합니다. 프롬프트를 제출하지는 않습니다. \n에 의존하는 대신 submit: true 또는 inputKeys: ["enter"]를 사용하는 것을 권장합니다.
// 기본값: 20줄, 5KB
interactive_shell({ sessionId: "calm-reef" })
// 더 많은 줄 (최대: 200줄)
...
서브에이전트 (subagent)가 작업을 마치면, Ctrl+T를 눌러 해당 출력을 캡처하고 메인 에이전트 (main agent)로 직접 전송할 수 있습니다:
[서브에이전트 작업 완료]
↓
[Ctrl+T 누름]
...
그러면 메인 에이전트는 컨텍스트 (context) 내에 서브에이전트의 응답을 갖게 되며, 해당 정보를 바탕으로 작업을 계속할 수 있습니다.
설정 (Configuration):
transferLines: 캡처할 최대 줄 수 (기본값: 200)
transferMaxChars: 최대 글자 수 (기본값: 20KB)
세션은 사용자에 의해 (Ctrl+B, 또는 Ctrl+Q → "Run in background") 또는 에이전트에 의해 백그라운드로 전환될 수 있습니다:
// 에이전트가 활성 세션을 백그라운드로 전환
interactive_shell({ sessionId: "calm-reef", background: true })
// → 오버레이가 닫히고 프로세스는 계속 실행됨
...
모니터 세션 (Monitor sessions)도 동일하게 작동합니다. 이들은 완료 시점이 아닌 모니터 이벤트 발생 시 깨어나는 헤드리스 (headless) 백그라운드 세션입니다.
사용자는 또한 /spawn을 통해 설정된 기본 스폰 에이전트 (default spawn agent)를 실행하거나, /spawn codex, /spawn cursor, /spawn claude, /spawn pi, /spawn fork, 또는 /spawn pi fork를 실행할 수 있습니다. --worktree를 추가하세요.
별도의 git worktree에서 스폰하려면, 예를 들어 /spawn cursor --worktree, /spawn codex --worktree, 또는 /spawn pi fork --worktree를 실행할 수 있습니다. 일반적인 /spawn cursor는 정상적인 대화형 오버레이 (interactive overlay) 상태를 유지합니다. fork는 Pi 전용입니다. Worktree는 그대로 유지되며, 오버레이가 생성된 위치를 알려줍니다. /attach 또는 /attach <id>를 사용하면 다시 연결 (reattach)할 수 있고, /dismiss 또는 /dismiss <id>를 사용하면 채팅에서 정리합니다. 키보드 스폰 단축키는 /spawn과 별개이며 spawn.shortcut을 사용합니다.
따옴표로 묶인 프롬프트 텍스트에 --hands-free 또는 --dispatch를 추가하면, /spawn은 단순한 대화형 오버레이 대신 모니터링되는 위임 실행 (monitored delegated run)으로 전환됩니다. 이는 구조화된 interactive_shell({ spawn: ... })와 동일한 리졸버 (resolver) 및 기본값을 공유합니다. 일반적인 /spawn은 대화형 (interactive) 상태를 유지합니다. Ctrl+G는 이러한 모니터링 세션 중 하나를 사용자가 제어하기 시작한 후에만 적용됩니다.
/spawn cursor "review the diffs" --dispatch
/spawn claude "review the diffs" --dispatch
/spawn codex "fix the failing tests" --hands-free
...
| 키 | 동작 |
|---|---|
| Ctrl+T | 전송 및 종료 (Transfer & close) - 출력을 캡처하여 메인 에이전트 (main agent)로 전송 |
| ... |
설정 파일 (프로젝트 설정이 전역 설정을 덮어씁니다):
전역 (Global): ~/.pi/agent/interactive-shell.json
프로젝트 (Project): .pi/interactive-shell.json
단축키 설정은 시작 시 고정됩니다. focusShortcut 또는 spawn.shortcut을 변경한 경우, 이를 적용하려면 Pi를 다시 로드하거나 재시작하십시오.
{
"overlayWidthPercent": 95,
"overlayHeightPercent": 60,
...
}