interminai
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese🌀 an Interactive Terminal for AI (interminai)
🌀 面向AI的交互式终端(interminai)
Author: Michael S. Tsirkin mst@kernel.org
A terminal proxy for interactive CLI applications. See examples.md and reference.md for details.
作者:Michael S. Tsirkin mst@kernel.org
一款用于交互式CLI应用的终端代理工具。详情请查看examples.md和reference.md。
When to Use
适用场景
Use for interactive commands that wait for input, show menus/prompts, or use full-screen interfaces (vim, git rebase -i, htop, apt, w3m).
**Use if you get errors like this "Warning: Output is not to a terminal" or "Warning: Input is not from a terminal".
Don't use for simple commands that just run and exit - use Shell instead.
适用于交互式命令:等待输入、显示菜单/提示或使用全屏界面的命令(如vim、git rebase -i、htop、apt、w3m)。
适用于出现以下错误的情况:"Warning: Output is not to a terminal" 或 "Warning: Input is not from a terminal"。
不适用于:仅运行后直接退出的简单命令——此类命令请使用Shell执行。
Quick Start
快速开始
bash
undefinedbash
undefined1. Start session (prints socket path to use in subsequent commands)
1. 启动会话(打印后续命令需使用的套接字路径)
./scripts/interminai start -- vim /tmp/test.txt
./scripts/interminai start -- vim /tmp/test.txt
Output:
输出:
PID: 12345
PID: 12345
Socket: /tmp/interminai-aBc123/socket
Socket: /tmp/interminai-aBc123/socket
Auto-generated: true
Auto-generated: true
2. Use the socket path shown above for all subsequent commands
2. 使用上述显示的套接字路径执行所有后续命令
./scripts/interminai input --socket /tmp/interminai-aBc123/socket --text ':wq\r'
./scripts/interminai input --socket /tmp/interminai-aBc123/socket --text ':wq\r'
3. Check screen
3. 查看屏幕内容
./scripts/interminai output --socket /tmp/interminai-aBc123/socket
./scripts/interminai output --socket /tmp/interminai-aBc123/socket
4. Clean up (always!)
4. 清理会话(务必执行!)
./scripts/interminai stop --socket /tmp/interminai-aBc123/socket
Just read the socket path from the `start` output and use it directly - no need to parse into variables../scripts/interminai stop --socket /tmp/interminai-aBc123/socket
直接从`start`命令的输出中读取套接字路径即可,无需解析为变量。Essential Commands
核心命令
- - Start application (prints socket path on stdout)
start -- COMMAND - - Send input (escapes:
input --socket PATH --text 'text'\r\n\e\tsee also: "Pressing Enter")\xHH - - Get screen (80x25 by default, add
output --socket PATHfor cursor position)--cursor print - - Check running state and activity flag
status --socket PATH - - Check if running (exit 0) or exited (exit 1, prints exit code)
status --socket PATH --quiet - - Wait for activity (any output), prints activity and exit status
wait --socket PATH - - Wait for process to exit (prints exit code)
wait --socket PATH --quiet - - Wait until line N changes (1-based)
wait --socket PATH --line N - - Wait until line N does NOT contain PATTERN
wait --socket PATH --line N --not-contains PATTERN - - Wait until line N contains PATTERN
wait --socket PATH --line N --contains PATTERN - - Stop session (also cleans up auto-generated socket)
stop --socket PATH
- - 启动应用(在标准输出打印套接字路径)
start -- COMMAND - - 发送输入(转义字符:
input --socket PATH --text 'text'\r\n\e\t,另请参阅:“按下回车键”部分)\xHH - - 获取屏幕内容(默认80x25,添加
output --socket PATH可显示光标位置)--cursor print - - 检查运行状态和活动标志
status --socket PATH - - 检查进程是否运行(运行则退出码0,已退出则退出码1并打印退出码)
status --socket PATH --quiet - - 等待活动(任意输出),打印活动状态和退出状态
wait --socket PATH - - 等待进程退出(打印退出码)
wait --socket PATH --quiet - - 等待第N行内容变化(行号从1开始)
wait --socket PATH --line N - - 等待第N行不包含指定模式
wait --socket PATH --line N --not-contains PATTERN - - 等待第N行包含指定模式
wait --socket PATH --line N --contains PATTERN - - 停止会话(同时清理自动生成的套接字)
stop --socket PATH
Key Best Practices
关键最佳实践
- Auto-generated sockets: Don't specify on start, read the path from output
--socket - Always clean up: when done (auto-cleans socket)
stop - Check output after each input - don't blindly chain commands
- Add delays: after input for processing
sleep 0.2 - Set GIT_EDITOR=vim for git rebase -i, git commit, etc.
- If screen garbled: Send (Ctrl+L) to redraw
\f - Wait for updates: If screen isn't updating, use instead of repeatedly calling
timeout 10 interminai wait --socket PATHoutput - Output is limited: No need to pipe to head/tail - output always ever gives you one screen. 25 lines by default.
- 自动生成套接字:启动时无需指定,从输出中读取路径即可
--socket - 务必清理会话:使用完毕后执行(自动清理套接字)
stop - 每次输入后检查输出 - 不要盲目链式执行命令
- 添加延迟:输入后添加等待处理
sleep 0.2 - 设置GIT_EDITOR=vim:用于git rebase -i、git commit等操作
- 屏幕内容乱码时:发送(Ctrl+L)重新绘制屏幕
\f - 等待更新:如果屏幕未更新,使用替代重复调用
timeout 10 interminai wait --socket PATHoutput - 输出有限制:无需通过管道传递给head/tail——输出始终仅返回一屏内容,默认25行。
Checking Activity (Recommended for LLMs)
检查活动状态(推荐LLM使用)
Use to check if there's new terminal output without blocking. This is
useful if you are running e.g. LLMs like Claude or Codex and want to decide
whether to fetch new output or wait longer.
statusbash
./scripts/interminai status --socket /tmp/interminai-xxx/socket使用命令无需阻塞即可检查是否有新的终端输出。如果你正在运行Claude或Codex等LLM,想要决定是获取新输出还是继续等待时,这会非常有用。
statusbash
./scripts/interminai status --socket /tmp/interminai-xxx/socketOutput:
输出:
Running: true
Running: true
Activity: true
Activity: true
**Pattern for efficient polling:**
```bash
**高效轮询模式**:
```bashAfter sending input, check if there's activity before fetching output
发送输入后,在获取输出前检查是否有活动
./scripts/interminai input --socket $SOCK --text 'make build\r'
sleep 0.5
./scripts/interminai input --socket $SOCK --text 'make build\r'
sleep 0.5
Check activity without blocking
非阻塞式检查活动状态
./scripts/interminai status --socket $SOCK
./scripts/interminai status --socket $SOCK
If Activity: true, fetch output
如果Activity: true,则获取输出
If Activity: false, wait longer or send more input
如果Activity: false,则等待更长时间或发送更多输入
This avoids repeatedly calling `output` when nothing has changed, saving context window
space and reducing noise. The activity flag is set when PTY output is received and
cleared by `status` or `wait`.
这避免了在无内容变化时重复调用`output`,节省上下文窗口空间并减少冗余信息。当接收到PTY输出时会设置活动标志,调用`status`或`wait`时会清除该标志。Waiting for CLI LLM Idle State (cursor-agent, codex, etc.)
等待CLI LLM空闲状态(cursor-agent、codex等)
When supervising CLI LLMs like cursor-agent, you need to detect when they finish
processing and are waiting for input.
Busy/Idle Indicators by CLI LLM:
| CLI | Busy Pattern | Idle Pattern |
|---|---|---|
| cursor-agent | | |
| codex | | |
| gemini | | |
| claude | | |
Approval prompts:
- cursor-agent: "Run this command?" dialog
- codex: Shows command and waits for y/n
- gemini: "Allow execution of: ..." modal with options
- claude: Permission prompts (unless using --dangerously-skip-permissions)
Detection Strategy (line-based wait):
- Find the line number containing the input prompt (e.g., line with )
ctrl+c to stop - Wait until that line no longer contains
ctrl+c to stop
Example: Supervising cursor-agent
bash
undefined当监督cursor-agent等CLI LLM时,你需要检测它们何时完成处理并等待输入。
各CLI LLM的忙碌/空闲指示器:
| CLI | 忙碌模式 | 空闲模式 |
|---|---|---|
| cursor-agent | 输入行显示 | 显示 |
| codex | 显示 | 显示 |
| gemini | 显示 | 输入框显示 |
| claude | 显示 | 显示 |
批准提示:
- cursor-agent:“Run this command?”对话框
- codex:显示命令并等待y/n输入
- gemini:“Allow execution of: ...”模态窗口及选项
- claude:权限提示(除非使用--dangerously-skip-permissions参数)
检测策略(基于行的等待):
- 找到包含输入提示符的行号(例如,包含的行)
ctrl+c to stop - 等待该行不再包含
ctrl+c to stop
示例:监督cursor-agent
bash
undefinedStart cursor-agent
启动cursor-agent
./scripts/interminai start --size 120x40 -- cursor-agent
./scripts/interminai start --size 120x40 -- cursor-agent
Output: Socket: /tmp/interminai-xxx/socket
输出: Socket: /tmp/interminai-xxx/socket
SOCK=/tmp/interminai-xxx/socket
SOCK=/tmp/interminai-xxx/socket
Send a prompt
发送提示
./scripts/interminai input --socket $SOCK --text 'Write hello world in Python'
sleep 0.1
./scripts/interminai input --socket $SOCK --text '\r'
./scripts/interminai input --socket $SOCK --text 'Write hello world in Python'
sleep 0.1
./scripts/interminai input --socket $SOCK --text '\r'
Find the line with ctrl+c to stop (the input prompt line during generation)
找到包含ctrl+c to stop的行(生成期间的输入提示行)
This line number may vary based on screen content
该行号可能因屏幕内容而异
./scripts/interminai output --socket $SOCK --no-color > /tmp/screen.txt
INPUT_LINE=$(grep -n 'ctrl+c to stop' /tmp/screen.txt | head -1 | cut -d: -f1)
./scripts/interminai output --socket $SOCK --no-color > /tmp/screen.txt
INPUT_LINE=$(grep -n 'ctrl+c to stop' /tmp/screen.txt | head -1 | cut -d: -f1)
Wait for that line to no longer contain 'ctrl+c to stop'
等待该行不再包含ctrl+c to stop
timeout 120 ./scripts/interminai wait --socket $SOCK
--line $INPUT_LINE --not-contains 'ctrl+c to stop'
--line $INPUT_LINE --not-contains 'ctrl+c to stop'
timeout 120 ./scripts/interminai wait --socket $SOCK
--line $INPUT_LINE --not-contains 'ctrl+c to stop'
--line $INPUT_LINE --not-contains 'ctrl+c to stop'
Now cursor-agent is idle (or showing approval prompt), check output
现在cursor-agent处于空闲状态(或显示批准提示),检查输出
SCREEN=$(./scripts/interminai output --socket $SOCK --no-color)
SCREEN=$(./scripts/interminai output --socket $SOCK --no-color)
Check what state we're in
检查当前状态
if echo "$SCREEN" | grep -q 'Run this command?'; then
Approval prompt - approve with 'y' or skip with 'n'
./scripts/interminai input --socket $SOCK --text 'y'
else
Idle - ready for next command
echo "cursor-agent is idle"
fi
**Why line-based?** The input line number stays relatively stable during generation.
Waiting for that specific line to change avoids false positives from pattern matches
elsewhere on screen.if echo "$SCREEN" | grep -q 'Run this command?'; then
批准提示 - 输入'y'批准或'n'跳过
./scripts/interminai input --socket $SOCK --text 'y'
else
空闲状态 - 准备好接收下一条命令
echo "cursor-agent is idle"
fi
**为什么基于行?** 生成期间输入行的行号相对稳定。等待特定行的变化可避免屏幕其他位置的模式匹配导致误判。Terminal Size
终端尺寸
Default terminal size is 80x24. If not enough context fits on screen, use on start or to increase the window. Don't go overboard to avoid filling your context with excessive output.
--sizeresizebash
undefined默认终端尺寸为80x24。如果屏幕无法容纳足够的上下文,可在启动时使用参数或使用命令增大窗口。不要设置过大,以免上下文被过多输出占用。
--sizeresizebash
undefinedStart with larger terminal
以更大的终端尺寸启动
./scripts/interminai start --size 80x256 -- COMMAND
./scripts/interminai start --size 80x256 -- COMMAND
Or resize during session (use socket path from start output)
或在会话期间调整尺寸(使用start命令输出中的套接字路径)
./scripts/interminai resize --socket /tmp/interminai-xxx/socket --size 80x256
undefined./scripts/interminai resize --socket /tmp/interminai-xxx/socket --size 80x256
undefinedVim Navigation Tips
Vim导航技巧
Exact counts for /// are critical - cursor position after isn't always intuitive. Prefer:
hjkldd- - Go to line directly (
:<number>):5\rdd - - Search for text (
/<pattern>)/goodbye\rdd - /
gg- Anchor from known positionG - - Check position after operations
--cursor print - - Search and replace with confirmation (
:%s/old/new/gc/yfor each match)n
hjkldd- - 直接跳转到指定行(
:<number>):5\rdd - - 搜索文本(
/<pattern>)/goodbye\rdd - /
gg- 从已知位置定位G - - 操作后检查光标位置
--cursor print - - 带确认的搜索替换(每个匹配项输入
:%s/old/new/gc/y确认)n
Complex Edits Shortcut
复杂编辑快捷方式
For complex multi-line edits, another option is to edit outside vim:
- Use to observe the file name
output - Use the Edit tool to modify the file directly
- In vim, reload the file () or simply exit (
:e!\r):q!\r
This avoids tricky vim navigation for large or intricate changes.
However, if editing is going to use sed anyway, using :%s/old/new/gc within vim
is more robust and more powerful as it shows you each change.
对于复杂的多行编辑,另一种选择是在vim外部编辑:
- 使用命令查看文件名
output - 使用编辑工具直接修改文件
- 在vim中重新加载文件()或直接退出(
:e!\r):q!\r
这避免了针对大型或复杂修改进行繁琐的vim导航。
不过,如果编辑本来就打算使用sed,那么在vim中使用会更可靠、功能更强大,因为它会显示每一处修改。
:%s/old/new/gcPressing Enter: \n
vs \r
\n\r按下回车键:\n
vs \r
\n\rTraditional Unix apps accept either (LF) or (CR) for Enter because the
kernel TTY driver translates CR to LF when the ICRNL flag is set (default in
"cooked" mode). However, some modern apps (especially React/Ink-based TUIs like
cursor-agent) run in raw mode with ICRNL disabled, and only recognize .
\n\r\rBest practice: Always use for Enter/submit. It works universally:
\r- Traditional apps: kernel translates →
\r(if ICRNL set)\n - Raw-mode apps: receive directly as expected
\r
Use only when you specifically want to add a newline to multiline input
(like continuing to type on a new line without submitting).
\nbash
undefined传统Unix应用接受(LF)或(CR)作为回车键,因为内核TTY驱动在ICRNL标志设置为开启时(“熟模式”默认设置)会将CR转换为LF。但一些现代应用(尤其是基于React/Ink的TUI,如cursor-agent)在原始模式下运行,ICRNL标志被禁用,仅识别。
\n\r\r最佳实践:始终使用作为回车键/提交键,可通用:
\r- 传统应用:内核会将转换为
\r(如果ICRNL开启)\n - 原始模式应用:直接接收符合预期
\r
仅当你需要在多行输入中添加换行符(如在新行继续输入但不提交)时才使用。
\nbash
undefinedSubmit a command (use \r)
提交命令(使用\r)
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'hello world\r'
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'hello world\r'
Multiline input (use \n for newlines, \r to submit)
多行输入(使用\n换行,\r提交)
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'line1\nline2\nline3\r'
undefined./scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'line1\nline2\nline3\r'
undefinedMenu prompts needing Enter
需要按下回车键的菜单提示
For git add -i/-p, the menu shown is not interactive, an action does not
take effect until you press enter. For example:
- Stage this hunk [y,n,q,a,d,K,j,J,g,/,e,?]?
Actually expects followed by Enter and will not take effect until Enter is sent.
yIf you observe a tool is waiting for Enter once, it is safe to assume
it will be waiting for it next time, too.
对于git add -i/-p,显示的菜单并非交互式,操作需按下回车键才会生效。例如:
- Stage this hunk [y,n,q,a,d,K,j,J,g,/,e,?]?
实际上需要输入后按回车键,否则操作不会生效。
y如果你观察到某个工具需要按一次回车键,那么可以假设它后续也需要按回车键。
Modern TUI Apps (Ink/React-based)
现代TUI应用(基于Ink/React)
Apps built with React/Ink (like cursor-agent) need a delay between typing text
and pressing Enter. Sending text and Enter in a single input call doesn't work
because React's internal state isn't ready for the Enter keystroke.
Key finding: Output polling alone is NOT sufficient. Even after text appears
on screen, React's state machine may not be ready. A time delay is required.
Simple pattern (recommended):
bash
undefined使用React/Ink构建的应用(如cursor-agent)在输入文本和按下回车键之间需要延迟。在单个输入调用中同时发送文本和回车键无效,因为React的内部状态尚未准备好处理回车键事件。
关键发现:仅轮询输出并不足够。即使文本已显示在屏幕上,React的状态机可能仍未准备好。必须添加时间延迟。
推荐的简单模式:
bash
undefinedSend text, wait, then send Enter
发送文本,等待,然后发送回车键
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'your prompt here'
sleep 0.1
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text '\r'
**Why this works**: The 100ms delay gives React's event loop time to process the
input and update its internal state before receiving the Enter keystroke.
Use `debug` command to check if app is in raw mode (no ICRNL flag)../scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'your prompt here'
sleep 0.1
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text '\r'
**为什么有效**:100ms的延迟为React事件循环提供了处理输入并更新内部状态的时间,之后再接收回车键事件。
使用`debug`命令检查应用是否处于原始模式(无ICRNL标志)。Long lived shell sessions
长期运行的Shell会话
It is possible to create a shell interminai session and pass commands to it.
Tip: Sudo caches credentials per-TTY. Each creates a new PTY,
so sudo prompts every time even if you recently authenticated elsewhere. Use a
long-lived shell session to run multiple sudo commands with a single password prompt.
interminai startbash
GIT_EDITOR=vim ./scripts/interminai start -- bash可以创建Shell的interminai会话并向其传递命令。
提示:Sudo按TTY缓存凭据。每次都会创建新的PTY,因此即使你最近在其他地方通过了认证,每次使用sudo仍会提示输入密码。使用长期运行的Shell会话可通过一次密码提示运行多个sudo命令。
interminai startbash
GIT_EDITOR=vim ./scripts/interminai start -- bashOutput shows: Socket: /tmp/interminai-xxx/socket
输出显示: Socket: /tmp/interminai-xxx/socket
sleep 0.5
./scripts/interminai output --socket /tmp/interminai-xxx/socket
sleep 0.5
./scripts/interminai output --socket /tmp/interminai-xxx/socket
... send commands now, using the socket path from above ...
... 现在使用上述套接字路径发送命令 ...
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'vim foo.txt\r'
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text ':wq\r'
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'vim bar.txt\r'
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text ':wq\r'
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'exit\r'
./scripts/interminai wait --socket /tmp/interminai-xxx/socket
undefined./scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'vim foo.txt\r'
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text ':wq\r'
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'vim bar.txt\r'
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text ':wq\r'
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text 'exit\r'
./scripts/interminai wait --socket /tmp/interminai-xxx/socket
undefinedGit Example
Git示例
bash
GIT_EDITOR=vim ./scripts/interminai start -- git rebase -i HEAD~3bash
GIT_EDITOR=vim ./scripts/interminai start -- git rebase -i HEAD~3Output shows: Socket: /tmp/interminai-xxx/socket
输出显示: Socket: /tmp/interminai-xxx/socket
sleep 0.5
./scripts/interminai output --socket /tmp/interminai-xxx/socket
sleep 0.5
./scripts/interminai output --socket /tmp/interminai-xxx/socket
... edit with input commands, using the socket path from above ...
... 使用上述套接字路径发送输入命令进行编辑 ...
./scripts/interminai input --socket /tmp/interminai-xxx/socket --text ':wq\r'
./scripts/interminai wait --socket /tmp/interminai-xxx/socket
**Piping output**: By default, output includes colors - do NOT use `--no-color` for normal viewing.
Only add `--no-color` when piping to grep/head/tail to avoid ANSI escape corruption:
```bash./scripts/interminai input --socket /tmp/interminai-xxx/socket --text ':wq\r'
./scripts/interminai wait --socket /tmp/interminai-xxx/socket
**输出管道**:默认输出包含颜色——正常查看时请勿使用`--no-color`。只有在通过管道传递给grep/head/tail时才添加`--no-color`,避免ANSI转义序列损坏输出:
```bashNormal viewing - no --no-color flag:
正常查看 - 不添加--no-color标志:
./scripts/interminai output --socket /tmp/interminai-xxx/socket
./scripts/interminai output --socket /tmp/interminai-xxx/socket
Piping to grep/head/tail - add --no-color:
通过管道传递给grep/head/tail - 添加--no-color:
./scripts/interminai output --socket /tmp/interminai-xxx/socket --no-color | grep pattern
./scripts/interminai output --socket /tmp/interminai-xxx/socket --no-color | tail -5
See [reference.md](reference.md) for full command documentation../scripts/interminai output --socket /tmp/interminai-xxx/socket --no-color | grep pattern
./scripts/interminai output --socket /tmp/interminai-xxx/socket --no-color | tail -5
完整命令文档请查看[reference.md](reference.md)。Password Input
密码输入
When a command prompts for a password (sudo, ssh, etc.), do not try to handle the
password yourself. Instead, tell the user to run themselves:
interminai input --passwordbash
./scripts/interminai start -- sudo apt update当命令提示输入密码时(如sudo、ssh等),请勿自行处理密码。相反,请告知用户自行运行:
interminai input --passwordbash
./scripts/interminai start -- sudo apt updateOutput shows: Socket: /tmp/interminai-xxx/socket
输出显示: Socket: /tmp/interminai-xxx/socket
sleep 0.5
./scripts/interminai output --socket /tmp/interminai-xxx/socket
sleep 0.5
./scripts/interminai output --socket /tmp/interminai-xxx/socket
Shows: [sudo] password for user:
显示: [sudo] password for user:
IMPORTANT: Tell the user to run interminai input --password
重要提示:告知用户运行interminai input --password
echo "Password required. Please run: interminai input --socket /tmp/interminai-xxx/socket --password"
echo "需要输入密码,请执行:interminai input --socket /tmp/interminai-xxx/socket --password"
User runs the command, types password, and it's sent to sudo
用户执行该命令,输入密码并按回车键提交(以\r发送)
./scripts/interminai wait --socket /tmp/interminai-xxx/socket
The `--password` flag:
- Prompts user to type password and press Enter to submit (sent as `\r`)
- Reads input with echo disabled (password not visible)./scripts/interminai wait --socket /tmp/interminai-xxx/socket
`--password`标志的作用:
- 提示用户输入密码并按回车键提交(以`\r`发送)
- 禁用回显读取输入(密码不可见)