interactive-shell

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Interactive Shell (Skill)

Interactive Shell（技能）

Last verified: 2026-01-18

最后验证时间：2026-01-18

Foreground vs Background Subagents

前台子代理 vs 后台子代理

Pi has two ways to delegate work to other AI coding agents:

	Foreground Subagents	Dispatch Subagents	Background Subagents
Tool	`interactive_shell`	`interactive_shell` (dispatch)	`subagent`
Visibility	User sees overlay	User sees overlay (or headless)	Hidden from user
Agent model	Polls for status	Notified on completion	Full output captured
Default agent	`pi` (others if user requests)	`pi` (others if user requests)	Pi only
User control	Can take over anytime	Can take over anytime	No intervention
Best for	Long tasks needing supervision	Fire-and-forget delegations	Parallel tasks, structured delegation

Foreground subagents run in an overlay where the user watches (and can intervene). Use

interactive_shell

with

mode: "hands-free"

to monitor while receiving periodic updates, or

mode: "dispatch"

to be notified on completion without polling.

Dispatch subagents also use

interactive_shell

but with

mode: "dispatch"

. The agent fires the session and moves on. When the session completes, the agent is woken up via

triggerTurn

with the output in context. Add

background: true

for headless execution (no overlay).

Background subagents run invisibly via the

subagent

tool. Pi-only, but captures full output and supports parallel execution.

Pi有两种将任务委托给其他AI编码代理的方式：

	前台子代理	调度子代理	后台子代理
工具	`interactive_shell`	`interactive_shell` （调度模式）	`subagent`
可见性	用户可见覆盖层	用户可见覆盖层（或无界面）	对用户隐藏
代理模型	轮询状态	完成时通知	捕获完整输出
默认代理	`pi` （用户指定时可切换其他代理）	`pi` （用户指定时可切换其他代理）	仅Pi
用户控制	可随时接管	可随时接管	无法干预
最佳适用场景	需要监控的长期任务	一次性委托任务	并行任务、结构化委托

前台子代理在覆盖层中运行，用户可以查看（并干预）。使用

interactive_shell

并设置

mode: "hands-free"

可在监控的同时接收定期更新，或设置

mode: "dispatch"

在任务完成时接收通知，无需轮询。

调度子代理同样使用

interactive_shell

，但需设置

mode: "dispatch"

。代理启动会话后即可继续其他工作，会话完成时，会通过

triggerTurn

唤醒代理并将输出纳入上下文。添加

background: true

可实现无界面执行（无覆盖层）。

后台子代理通过

subagent

工具在后台隐形运行。仅支持Pi，但可捕获完整输出并支持并行执行。

When to Use Foreground Subagents

何时使用前台子代理

Use

interactive_shell

(foreground) when:

The task is long-running and the user should see progress
The user might want to intervene or guide the agent
You want hands-free monitoring with periodic status updates
You need a different agent's capabilities (only if user specifies)

Use

subagent

(background) when:

You need parallel execution of multiple tasks
You want full output capture for processing
The task is quick and deterministic
User doesn't need to see the work happening

在以下场景使用

interactive_shell

（前台模式）：

任务长期运行，用户需要查看进度
用户可能需要干预或引导代理
你需要免手动监控并接收定期状态更新
你需要其他代理的能力（仅当用户指定时）

在以下场景使用

subagent

（后台模式）：

你需要并行执行多个任务
你需要捕获完整输出用于后续处理
任务快速且确定
用户无需查看任务执行过程

Default Agent Choice

默认代理选择

Default to
pi
for foreground subagents unless the user explicitly requests a different agent:

User says	Agent to use
"Run this in hands-free"	`pi`
"Delegate this task"	`pi`
"Use Claude to review this"	`claude`
"Have Gemini analyze this"	`gemini`
"Run aider to fix this"	`aider`

Pi is the default because it's already available, has the same capabilities, and maintains consistency. Only use Claude, Gemini, Codex, or other agents when the user specifically asks for them.

**默认使用

pi

**作为前台子代理，除非用户明确要求其他代理：

用户指令	应使用的代理
"以免手动模式运行此任务"	`pi`
"委托此任务"	`pi`
"使用Claude审核此内容"	`claude`
"让Gemini分析此内容"	`gemini`
"运行aider修复此问题"	`aider`

Pi作为默认代理是因为它已就绪、具备相同能力且能保持一致性。仅当用户明确要求时，才使用Claude、Gemini、Codex或其他代理。

Foreground Subagent Modes

前台子代理模式

Interactive (default)

交互式（默认）

User has full control, types directly into the agent.

typescript

interactive_shell({ command: 'pi' })

用户拥有完全控制权，可直接向代理输入内容。

typescript

interactive_shell({ command: 'pi' })

Interactive with Initial Prompt

带初始提示的交互式

Agent starts working immediately, user supervises.

typescript

interactive_shell({ command: 'pi "Review this codebase for security issues"' })

代理立即开始工作，用户进行监控。

typescript

interactive_shell({ command: 'pi "Review this codebase for security issues"' })

Dispatch (Fire-and-Forget) - NON-BLOCKING, NO POLLING

调度（一次性委托）- 非阻塞、无需轮询

Agent fires a session and moves on. Notified automatically on completion via

triggerTurn

typescript

// Start session - returns immediately, no polling needed
interactive_shell({
  command: 'pi "Fix all TypeScript errors in src/"',
  mode: "dispatch",
  reason: "Fixing TS errors"
})
// Returns: { sessionId: "calm-reef", mode: "dispatch" }
// → Do other work. When session completes, you receive notification with output.

Dispatch defaults

autoExitOnQuiet: true

. The agent can still query the sessionId if needed, but doesn't have to.

代理启动会话后即可继续其他工作，任务完成时会自动收到通知。

typescript

// 启动会话 - 立即返回，无需轮询
interactive_shell({
  command: 'pi "Fix all TypeScript errors in src/"',
  mode: "dispatch",
  reason: "Fixing TS errors"
})
// 返回：{ sessionId: "calm-reef", mode: "dispatch" }
// → 继续其他工作。会话完成后，你会收到包含输出的通知。

调度模式默认

autoExitOnQuiet: true

。代理仍可查询sessionId，但非必须。

Background Dispatch (Headless)

后台调度（无界面）

No overlay opens. Multiple headless dispatches can run concurrently:

typescript

interactive_shell({
  command: 'pi "Fix lint errors"',
  mode: "dispatch",
  background: true
})
// → No overlay. User can /attach to watch. Agent notified on completion.

不会打开覆盖层，可同时运行多个无界面调度任务：

typescript

interactive_shell({
  command: 'pi "Fix lint errors"',
  mode: "dispatch",
  background: true
})
// → 无覆盖层。用户可通过/attach命令查看，代理会在任务完成时收到通知。

Hands-Free (Foreground Subagent) - NON-BLOCKING

免手动模式（前台子代理）- 非阻塞

Agent works autonomously, returns immediately with sessionId. You query for status/output and kill when done.

typescript

// 1. Start session - returns immediately
interactive_shell({
  command: 'pi "Fix all TypeScript errors in src/"',
  mode: "hands-free",
  reason: "Fixing TS errors"
})
// Returns: { sessionId: "calm-reef", status: "running" }

// 2. Check status and get new output
interactive_shell({ sessionId: "calm-reef" })
// Returns: { status: "running", output: "...", runtime: 30000 }

// 3. When you see task is complete, kill session
interactive_shell({ sessionId: "calm-reef", kill: true })
// Returns: { status: "killed", output: "final output..." }

This is the primary pattern for foreground subagents - you delegate to pi (or another agent), query for progress, and decide when the task is done.

代理自主工作，立即返回sessionId。你可查询状态/输出，并在完成时终止会话。

typescript

// 1. 启动会话 - 立即返回
interactive_shell({
  command: 'pi "Fix all TypeScript errors in src/"',
  mode: "hands-free",
  reason: "Fixing TS errors"
})
// 返回：{ sessionId: "calm-reef", status: "running" }

// 2. 检查状态并获取新输出
interactive_shell({ sessionId: "calm-reef" })
// 返回：{ status: "running", output: "...", runtime: 30000 }

// 3. 当发现任务完成时，终止会话
interactive_shell({ sessionId: "calm-reef", kill: true })
// 返回：{ status: "killed", output: "final output..." }

这是前台子代理的主要模式 - 你将任务委托给Pi（或其他代理），查询进度，并决定何时结束任务。

Hands-Free Workflow

免手动工作流

Starting a Session

启动会话

typescript

const result = interactive_shell({
  command: 'codex "Review this codebase"',
  mode: "hands-free"
})
// result.details.sessionId = "calm-reef"
// result.details.status = "running"

The user sees the overlay immediately. You get control back to continue working.

typescript

const result = interactive_shell({
  command: 'codex "Review this codebase"',
  mode: "hands-free"
})
// result.details.sessionId = "calm-reef"
// result.details.status = "running"

用户会立即看到覆盖层，你可继续其他工作。

Querying Status

查询状态

typescript

interactive_shell({ sessionId: "calm-reef" })

Returns:

```
status
```
: "running" | "user-takeover" | "exited" | "killed" | "backgrounded"
```
output
```
: Last 20 lines of rendered terminal (clean, no TUI animation noise)
```
runtime
```
: Time elapsed in ms

Rate limited: Queries are limited to once every 60 seconds. If you query too soon, the tool will automatically wait until the limit expires before returning. The user is watching the overlay in real-time - you're just checking in periodically.

typescript

interactive_shell({ sessionId: "calm-reef" })

返回内容：

```
status
```
: "running" | "user-takeover" | "exited" | "killed" | "backgrounded"
```
output
```
: 终端渲染内容的最后20行（无TUI动画干扰）
```
runtime
```
: 已运行时间（毫秒）

速率限制： 每60秒最多查询一次。如果查询过于频繁，工具会自动等待至限制过期后再返回结果。用户会实时查看覆盖层，你只需定期检查进度即可。

Ending a Session

结束会话

typescript

interactive_shell({ sessionId: "calm-reef", kill: true })

Kill when you see the task is complete in the output. Returns final status and output.

typescript

interactive_shell({ sessionId: "calm-reef", kill: true })

当你在输出中看到任务完成时，即可终止会话，返回最终状态和输出。

Fire-and-Forget Tasks

一次性任务

For single-task delegations where you don't need multi-turn interaction, enable auto-exit so the session kills itself when the agent goes quiet:

typescript

interactive_shell({
  command: 'pi "Review this codebase for security issues. Save your findings to /tmp/security-review.md"',
  mode: "hands-free",
  reason: "Security review",
  handsFree: { autoExitOnQuiet: true }
})
// Session auto-kills after ~5s of quiet
// Read results from file:
// read("/tmp/security-review.md")

Instruct subagent to save results to a file since the session closes automatically.

对于无需多轮交互的单次委托任务，启用自动退出功能，当代理停止输出时会自动终止会话：

typescript

interactive_shell({
  command: 'pi "Review this codebase for security issues. Save your findings to /tmp/security-review.md"',
  mode: "hands-free",
  reason: "Security review",
  handsFree: { autoExitOnQuiet: true }
})
// 代理停止输出约5秒后，会话自动终止
// 从文件读取结果：
// read("/tmp/security-review.md")

请指示子代理将结果保存到文件，因为会话会自动关闭。

Multi-Turn Sessions (default)

多轮会话（默认）

For back-and-forth interaction, leave auto-exit disabled (the default). Query status and kill manually when done:

typescript

interactive_shell({
  command: 'cursor-agent -f',
  mode: "hands-free",
  reason: "Interactive refactoring"
})

// Send follow-up prompts
interactive_shell({ sessionId: "calm-reef", input: "Now fix the tests\n" })

// Kill when done
interactive_shell({ sessionId: "calm-reef", kill: true })

如需来回交互，请保持自动退出功能禁用（默认状态）。手动查询状态并在完成时终止会话：

typescript

interactive_shell({
  command: 'cursor-agent -f',
  mode: "hands-free",
  reason: "Interactive refactoring"
})

// 发送后续提示
interactive_shell({ sessionId: "calm-reef", input: "Now fix the tests\n" })

// 完成后终止会话
interactive_shell({ sessionId: "calm-reef", kill: true })

Sending Input

发送输入

typescript

interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] })
interactive_shell({ sessionId: "calm-reef", inputPaste: "multi\nline\ncode" })
interactive_shell({ sessionId: "calm-reef", input: "y", inputKeys: ["enter"] })  // combine text + keys

typescript

interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] })
interactive_shell({ sessionId: "calm-reef", inputPaste: "multi\nline\ncode" })
interactive_shell({ sessionId: "calm-reef", input: "y", inputKeys: ["enter"] })  // 组合文本与按键

Query Output

查询输出

Status queries return rendered terminal output (what's actually on screen), not raw stream:

Default: 20 lines, 5KB max per query
No TUI animation noise (spinners, progress bars, etc.)
Configurable via
```
outputLines
```
(max: 200) and
```
outputMaxChars
```
(max: 50KB)

typescript

// Get more output when reviewing a session
interactive_shell({ sessionId: "calm-reef", outputLines: 50 })

// Get even more for detailed review
interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })

状态查询返回终端渲染输出（即屏幕实际显示内容），而非原始流：

默认：每次查询返回20行，最大5KB
无TUI动画干扰（如 spinner、进度条等）
可通过
```
outputLines
```
（最大200）和
```
outputMaxChars
```
（最大50KB）配置

typescript

// 查看会话时获取更多输出
interactive_shell({ sessionId: "calm-reef", outputLines: 50 })

// 详细审核时获取更多内容
interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })

Incremental Reading

增量读取

Use

incremental: true

to paginate through output without re-reading:

typescript

// First call: get first 50 lines
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: true }

// Next call: get next 50 lines (server tracks position)
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: true }

// Keep calling until hasMore: false
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: false }

The server tracks your read position - just keep calling with

incremental: true

to get the next chunk.

使用

incremental: true

可分页读取输出，无需重复读取：

typescript

// 首次调用：获取前50行
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: true }

// 下一次调用：获取接下来50行（服务器会跟踪读取位置）
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: true }

// 持续调用直到hasMore: false
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: false }

服务器会跟踪你的读取位置，只需持续调用

incremental: true

即可获取下一部分内容。

Reviewing Output

查看输出

Query sessions to see progress. Increase limits when you need more context:

typescript

// Default: last 20 lines
interactive_shell({ sessionId: "calm-reef" })

// Get more lines when you need more context
interactive_shell({ sessionId: "calm-reef", outputLines: 50 })

// Get even more for detailed review
interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })

查询会话以查看进度，需要更多上下文时可提高限制：

typescript

// 默认：最后20行
interactive_shell({ sessionId: "calm-reef" })

// 需要更多上下文时，获取更多行
interactive_shell({ sessionId: "calm-reef", outputLines: 50 })

// 详细审核时获取更多内容
interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })

Sending Input to Active Sessions

向活跃会话发送输入

Use the

sessionId

from updates to send input to a running hands-free session:

使用更新返回的

sessionId

向运行中的免手动会话发送输入：

Basic Input

基础输入

typescript

// Send text
interactive_shell({ sessionId: "shell-1", input: "/help\n" })

// Send text with keys
interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })

// Navigate menus
interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "enter"] })

// Interrupt
interactive_shell({ sessionId: "shell-1", inputKeys: ["ctrl+c"] })

typescript

// 发送文本
interactive_shell({ sessionId: "shell-1", input: "/help\n" })

// 发送文本并按键
interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })

// 导航菜单
interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "enter"] })

// 中断
interactive_shell({ sessionId: "shell-1", inputKeys: ["ctrl+c"] })

Named Keys

命名按键

Key	Description
`up` , `down` , `left` , `right`	Arrow keys
`enter` , `return`	Enter/Return
`escape` , `esc`	Escape
`tab` , `shift+tab` (or `btab` )	Tab / Back-tab
`backspace` , `bspace`	Backspace
`delete` , `del` , `dc`	Delete
`insert` , `ic`	Insert
`home` , `end`	Home/End
`pageup` , `pgup` , `ppage`	Page Up
`pagedown` , `pgdn` , `npage`	Page Down
`f1` - `f12`	Function keys
`kp0` - `kp9` , `kp/` , `kp*` , `kp-` , `kp+` , `kp.` , `kpenter`	Keypad keys
`ctrl+c` , `ctrl+d` , `ctrl+z`	Control sequences
`ctrl+a` through `ctrl+z`	All control keys

Note:

ic

dc

ppage

npage

bspace

are tmux-style aliases for compatibility.

按键	描述
`up` , `down` , `left` , `right`	方向键
`enter` , `return`	回车键
`escape` , `esc`	退出键
`tab` , `shift+tab` （或 `btab` ）	制表键 / 反向制表键
`backspace` , `bspace`	退格键
`delete` , `del` , `dc`	删除键
`insert` , `ic`	插入键
`home` , `end`	首页/尾页键
`pageup` , `pgup` , `ppage`	上翻页键
`pagedown` , `pgdn` , `npage`	下翻页键
`f1` - `f12`	功能键
`kp0` - `kp9` , `kp/` , `kp*` , `kp-` , `kp+` , `kp.` , `kpenter`	小键盘按键
`ctrl+c` , `ctrl+d` , `ctrl+z`	控制序列
`ctrl+a` 至 `ctrl+z`	所有控制键

注意：

ic

dc

、

ppage

npage

、

bspace

是tmux风格的别名，用于兼容性。

Modifier Combinations

组合键

Supports

ctrl+

alt+

shift+

prefixes (or shorthand

c-

m-

s-

typescript

// Cancel
inputKeys: ["ctrl+c"]

// Alt+Tab
inputKeys: ["alt+tab"]

// Ctrl+Alt+Delete
inputKeys: ["ctrl+alt+delete"]

// Shorthand syntax
inputKeys: ["c-c", "m-x", "s-tab"]

支持

ctrl+

、

alt+

、

shift+

前缀（或简写

c-

、

m-

、

s-

）：

typescript

// 取消
inputKeys: ["ctrl+c"]

// Alt+Tab
inputKeys: ["alt+tab"]

// Ctrl+Alt+Delete
inputKeys: ["ctrl+alt+delete"]

// 简写语法
inputKeys: ["c-c", "m-x", "s-tab"]

Hex Bytes (Advanced)

十六进制字节（高级）

Send raw escape sequences:

typescript

inputHex: ["0x1b", "0x5b", "0x41"]  // ESC[A (up arrow)

发送原始转义序列：

typescript

inputHex: ["0x1b", "0x5b", "0x41"]  // ESC[A（上箭头）

Bracketed Paste

括号粘贴

Paste multiline text without triggering autocompletion/execution:

typescript

inputPaste: "function foo() {\n  return 42;\n}"

粘贴多行文本，不会触发自动补全/执行：

typescript

inputPaste: "function foo() {\n  return 42;\n}"

Model Selection Example

模型选择示例

typescript

// Step 1: Open model selector
interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })

// Step 2: Filter and select (after ~500ms delay)
interactive_shell({ sessionId: "shell-1", input: "sonnet", inputKeys: ["enter"] })

// Or navigate with arrows:
interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "down", "enter"] })

typescript

// 步骤1：打开模型选择器
interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })

// 步骤2：筛选并选择（延迟约500ms后）
interactive_shell({ sessionId: "shell-1", input: "sonnet", inputKeys: ["enter"] })

// 或使用方向键导航：
interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "down", "enter"] })

Context Compaction

上下文压缩

typescript

interactive_shell({ sessionId: "shell-1", input: "/compact", inputKeys: ["enter"] })

typescript

interactive_shell({ sessionId: "shell-1", input: "/compact", inputKeys: ["enter"] })

Changing Update Settings

修改更新设置

Adjust timing during a session:

typescript

// Change max interval (fallback for on-quiet mode)
interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 120000 } })

// Change quiet threshold (how long to wait after output stops)
interactive_shell({ sessionId: "calm-reef", settings: { quietThreshold: 3000 } })

// Both at once
interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 30000, quietThreshold: 2000 } })

在会话运行期间调整时间设置：

typescript

// 修改最大间隔（无输出时的 fallback）
interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 120000 } })

// 修改无输出阈值（输出停止后等待的时间）
interactive_shell({ sessionId: "calm-reef", settings: { quietThreshold: 3000 } })

// 同时修改两者
interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 30000, quietThreshold: 2000 } })

CLI Quick Reference

CLI速查

Agent	Interactive	With Prompt	Headless (bash)	Dispatch
`claude`	`claude`	`claude "prompt"`	`claude -p "prompt"`	`mode: "dispatch"`
`gemini`	`gemini`	`gemini -i "prompt"`	`gemini "prompt"`	`mode: "dispatch"`
`codex`	`codex`	`codex "prompt"`	`codex exec "prompt"`	`mode: "dispatch"`
`agent`	`agent`	`agent "prompt"`	`agent -p "prompt"`	`mode: "dispatch"`
`pi`	`pi`	`pi "prompt"`	`pi -p "prompt"`	`mode: "dispatch"`

Gemini model:

gemini -m gemini-3-flash-preview -i "prompt"

代理	交互式	带提示	无界面（bash）	调度模式
`claude`	`claude`	`claude "prompt"`	`claude -p "prompt"`	`mode: "dispatch"`
`gemini`	`gemini`	`gemini -i "prompt"`	`gemini "prompt"`	`mode: "dispatch"`
`codex`	`codex`	`codex "prompt"`	`codex exec "prompt"`	`mode: "dispatch"`
`agent`	`agent`	`agent "prompt"`	`agent -p "prompt"`	`mode: "dispatch"`
`pi`	`pi`	`pi "prompt"`	`pi -p "prompt"`	`mode: "dispatch"`

Gemini模型：

gemini -m gemini-3-flash-preview -i "prompt"

Prompt Packaging Rules

提示打包规则

The

reason

parameter is UI-only - it's shown in the overlay header but NOT passed to the subprocess.

To give the agent an initial prompt, embed it in the

command

typescript

// WRONG - agent starts idle, reason is just UI text
interactive_shell({ command: 'claude', reason: 'Review the codebase' })

// RIGHT - agent receives the prompt
interactive_shell({ command: 'claude "Review the codebase"', reason: 'Code review' })

reason

参数仅用于UI - 它会显示在覆盖层标题中，但不会传递给子进程。

如需向代理发送初始提示，请将其嵌入

command

中：

typescript

// 错误示例 - 代理启动后处于空闲状态，reason仅为UI文本
interactive_shell({ command: 'claude', reason: 'Review the codebase' })

// 正确示例 - 代理会收到提示
interactive_shell({ command: 'claude "Review the codebase"', reason: 'Code review' })

Handoff Options

交接选项

Transfer (Ctrl+T) - Recommended

传输（Ctrl+T）- 推荐

When the subagent finishes, the user presses Ctrl+T to transfer output directly to you:

[Subagent finishes work in overlay]
        ↓
[User presses Ctrl+T]
        ↓
[You receive: "Session output transferred (150 lines):
  
  Completing skill integration...
  Modified files:
  - skills.ts
  - agents/types/..."]

This is the cleanest workflow - the subagent's response becomes your context automatically.

Configuration:

transferLines

(default: 200),

transferMaxChars

(default: 20KB)

当子代理完成任务后，用户按下Ctrl+T可将输出直接传输给主代理：

[子代理在覆盖层中完成工作]
        ↓
[用户按下Ctrl+T]
        ↓
[主代理收到："会话输出已传输（150行）：
  
  完成技能集成...
  修改的文件：
  - skills.ts
  - agents/types/..."]

这是最简洁的工作流 - 子代理的响应会自动成为主代理的上下文。

配置：

transferLines

（默认：200），

transferMaxChars

（默认：20KB）

Tail Preview (default)

尾部预览（默认）

Last 30 lines included in tool result. Good for seeing errors/final status.

工具结果中包含最后30行内容，适合查看错误或最终状态。

Snapshot to File

快照至文件

Write full transcript to

~/.pi/agent/cache/interactive-shell/snapshot-*.log

typescript

interactive_shell({
  command: 'claude "Fix bugs"',
  handoffSnapshot: { enabled: true, lines: 200 }
})

将完整记录写入

~/.pi/agent/cache/interactive-shell/snapshot-*.log

：

typescript

interactive_shell({
  command: 'claude "Fix bugs"',
  handoffSnapshot: { enabled: true, lines: 200 }
})

Artifact Handoff (for complex tasks)

工件交接（适用于复杂任务）

Instruct the delegated agent to write a handoff file:

Write your findings to .pi/delegation/claude-handoff.md including:
- What you did
- Files changed
- Any errors
- Next steps for the main agent

指示委托的代理写入交接文件：

将你的发现写入.pi/delegation/claude-handoff.md，内容包括：
- 你完成的工作
- 修改的文件
- 遇到的错误
- 主代理的下一步操作建议

Safe TUI Capture

安全TUI捕获

Never run TUI agents via bash - they hang even with

--help

. Use

interactive_shell

with

timeout

instead:

typescript

interactive_shell({
  command: "pi --help",
  mode: "hands-free",
  timeout: 5000  // Auto-kill after 5 seconds
})

The process is killed after timeout and captured output is returned in the handoff preview. This is useful for:

Getting CLI help from TUI applications
Capturing output from commands that don't exit cleanly
Any TUI command where you need quick output without user interaction

For pi CLI documentation, you can also read directly:

/opt/homebrew/lib/node_modules/@mariozechner/pi-coding-agent/README.md

永远不要通过bash运行TUI代理 - 即使使用

--help

也会挂起。请使用

interactive_shell

并设置

timeout

：

typescript

interactive_shell({
  command: "pi --help",
  mode: "hands-free",
  timeout: 5000  // 5秒后自动终止
})

超时后进程会被终止，捕获的输出会在交接预览中返回。这适用于：

从TUI应用获取CLI帮助
捕获无法正常退出的命令输出
任何无需用户交互即可快速获取输出的TUI命令

如需查看Pi CLI文档，你也可直接读取：

/opt/homebrew/lib/node_modules/@mariozechner/pi-coding-agent/README.md

Background Session Management

后台会话管理

typescript

// Background an active session (close overlay, keep running)
interactive_shell({ sessionId: "calm-reef", background: true })

// List all background sessions
interactive_shell({ listBackground: true })

// Reattach to a background session
interactive_shell({ attach: "calm-reef" })                    // interactive (blocking)
interactive_shell({ attach: "calm-reef", mode: "hands-free" })  // hands-free (poll)
interactive_shell({ attach: "calm-reef", mode: "dispatch" })    // dispatch (notified)

// Dismiss background sessions (kill running, remove exited)
interactive_shell({ dismissBackground: true })               // all
interactive_shell({ dismissBackground: "calm-reef" })        // specific

typescript

// 将活跃会话转为后台（关闭覆盖层，保持运行）
interactive_shell({ sessionId: "calm-reef", background: true })

// 列出所有后台会话
interactive_shell({ listBackground: true })

// 重新连接到后台会话
interactive_shell({ attach: "calm-reef" })                    // 交互式（阻塞）
interactive_shell({ attach: "calm-reef", mode: "hands-free" })  // 免手动（轮询）
interactive_shell({ attach: "calm-reef", mode: "dispatch" })    // 调度模式（完成时通知）

// 清除后台会话（终止运行中的会话，移除已退出的会话）
interactive_shell({ dismissBackground: true })               // 清除所有
interactive_shell({ dismissBackground: "calm-reef" })        // 清除指定会话

Quick Reference

快速参考

Dispatch subagent (fire-and-forget, default to pi):

typescript

interactive_shell({
  command: 'pi "Implement the feature described in SPEC.md"',
  mode: "dispatch",
  reason: "Implementing feature"
})
// Returns immediately. You'll be notified when done.

Background dispatch (headless, no overlay):

typescript

interactive_shell({
  command: 'pi "Fix lint errors"',
  mode: "dispatch",
  background: true,
  reason: "Fixing lint"
})

Start foreground subagent (hands-free, default to pi):

typescript

interactive_shell({
  command: 'pi "Implement the feature described in SPEC.md"',
  mode: "hands-free",
  reason: "Implementing feature"
})
// Returns sessionId in updates, e.g., "shell-1"

Send input to active session:

typescript

// Text with enter
interactive_shell({ sessionId: "calm-reef", input: "/compact\n" })

// Text + named keys
interactive_shell({ sessionId: "calm-reef", input: "/model", inputKeys: ["enter"] })

// Menu navigation
interactive_shell({ sessionId: "calm-reef", inputKeys: ["down", "down", "enter"] })

Change update frequency:

typescript

interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 60000 } })

Foreground subagent (user requested different agent):

typescript

interactive_shell({
  command: 'claude "Review this code for security issues"',
  mode: "hands-free",
  reason: "Security review with Claude"
})

Background subagent:

typescript

subagent({ agent: "scout", task: "Find all TODO comments" })

调度子代理（一次性委托，默认使用Pi）：

typescript

interactive_shell({
  command: 'pi "Implement the feature described in SPEC.md"',
  mode: "dispatch",
  reason: "Implementing feature"
})
// 立即返回，任务完成时你会收到通知。

后台调度（无界面，无覆盖层）：

typescript

interactive_shell({
  command: 'pi "Fix lint errors"',
  mode: "dispatch",
  background: true,
  reason: "Fixing lint"
})

启动前台子代理（免手动，默认使用Pi）：

typescript

interactive_shell({
  command: 'pi "Implement the feature described in SPEC.md"',
  mode: "hands-free",
  reason: "Implementing feature"
})
// 在更新中返回sessionId，例如"shell-1"

向活跃会话发送输入：

typescript

// 文本加回车键
interactive_shell({ sessionId: "calm-reef", input: "/compact\n" })

// 文本加命名按键
interactive_shell({ sessionId: "calm-reef", input: "/model", inputKeys: ["enter"] })

// 菜单导航
interactive_shell({ sessionId: "calm-reef", inputKeys: ["down", "down", "enter"] })

修改更新频率：

typescript

interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 60000 } })

前台子代理（用户指定其他代理）：

typescript

interactive_shell({
  command: 'claude "Review this code for security issues"',
  mode: "hands-free",
  reason: "Security review with Claude"
})

后台子代理：

typescript

subagent({ agent: "scout", task: "Find all TODO comments" })