mcpField
C
cli-anything-iterm2-ctl

cli-anything-iterm2-ctl

github.com/hkuds开发57.6k486 次安装5 周前更新
代码仓库

关于 cli-anything-iterm2-ctl

cli-anything-iterm2 是有状态的命令行工具封装，通过 WebSocket 和 iTerm2 Python API 控制正在运行的 iTerm2。它面向需要检查和操作终端会话、窗口、窗格、配置及布局的 Agent 和自动化流程。

主要功能

  1. 01快照查看工作区会话和上下文
  2. 02发送输入并读取屏幕或滚屏内容
  3. 03管理窗口、标签页和分屏
  4. 04保存和恢复窗口布局
  5. 05控制 tmux -CC 连接和窗口
  6. 06管理配置、偏好设置及菜单操作

适用场景

  1. 01检查现有工作区中的进程
  2. 02运行命令并收集终端输出
  3. 03建立或调整终端窗格布局
  4. 04向多个窗格广播按键

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/hkuds/cli-anything --skill cli-anything-iterm2-ctl

安装后在 Claude Code 中输入/cli-anything-iterm2-ctl确认已加载。

详细介绍

cli-anything-iterm2

面向 iTerm2 的有状态 CLI 封装工具。通过 WebSocket 使用 iTerm2 Python API 控制运行中的 iTerm2 进程。

前置条件

  1. macOS + iTerm2 正在运行：brew install --cask iterm2
  2. 已启用 Python API：iTerm2 → Preferences → General → Magic → Enable Python API
  3. 安装：pip install cli-anything-iterm2（或从源码执行 pip install -e .）

基本语法

cli-anything-iterm2 [--json] <group> <command> [OPTIONS] [ARGS]

始终使用 --json 以获得机器可读输出（Agent 使用时必需）。

命令分组

分组用途
app应用状态、工作区快照、上下文管理、应用级变量、模态对话框、文件面板
window创建、列出、关闭、调整大小、全屏窗口
tab创建、列出、关闭、激活标签页；按方向导航分屏窗格
session发送文本、注入原始字节、读取屏幕、完整回滚缓冲区、拆分窗格、提示词检测
profile列出配置文件、获取配置文件详情、列出/应用颜色预设
arrangement保存和恢复窗口布局
tmux完整的 tmux -CC 集成：引导、连接、窗口、命令
broadcast通过广播域在窗格间同步按键
menu以编程方式调用任意 iTerm2 菜单项
pref读写全局 iTerm2 首选项；列出所有有效键；tmux 设置

在现有工作区中定位

当你进入一个已有窗格的会话，且需要了解正在运行的内容而无需读取每个窗格的完整屏幕内容时，使用 app snapshot：

cli-anything-iterm2 --json app snapshot

返回所有窗口中每个会话的名称、当前目录、前台进程、user.role 标签以及最后可见的输出行。

命名约定 — 在设置工作区时为窗格添加标签，以便日后查找：

cli-anything-iterm2 session set-var user.role "api-server"
cli-anything-iterm2 session set-var user.role "log-tail"
cli-anything-iterm2 session set-var user.role "editor"

app snapshot 会将这些角色与进程和路径一起显示，让你一次调用即可获得完整画面。

典型 Agent 工作流

# 1. Orient — snapshot every session: name, path, process, role, last output line
cli-anything-iterm2 --json app snapshot

# 2. Establish context (saves window/tab/session IDs for subsequent commands)
cli-anything-iterm2 app current

# 3. Interact — no --session-id needed once context is set
cli-anything-iterm2 session send "git status"
cli-anything-iterm2 --json session scrollback --tail 200 --strip

# 4. Create a multi-pane workspace — label panes so snapshot identifies them later
cli-anything-iterm2 session split --vertical --use-as-context
cli-anything-iterm2 session send "python3 -m http.server 8000"
cli-anything-iterm2 session set-var user.role "http-server"

参考文件

只阅读任务所需的内容 — 每个文件只涉及一个狭窄的关注点（约 10–30 行）：

文件当你需要……时阅读
references/session-io.md发送文本、注入字节、读取屏幕/回滚缓冲区、获取选中内容
references/session-control.md拆分窗格、激活/关闭会话、调整大小、重命名、会话变量
references/session-shell-integration.mdwait-prompt、wait-command-end、get-prompt；可靠的发送→等待→读取模式
references/layout-window-tab.md创建/关闭/调整窗口和标签页大小、导航分屏窗格
references/layout-arrangement.md保存和恢复窗口布局
references/app-context.md快照（定位）、状态、上下文管理、应用变量、模态对话框、文件面板
references/profile-pref.md配置文件列表/获取/预设、首选项读/写、tmux 首选项快捷方式
references/broadcast-menu.md向多个窗格广播按键、调用菜单项
references/tmux-commands.md所有 tmux CLI 命令（bootstrap、send、tabs、create-window、set-visible）
references/tmux-guide.md完整的 tmux -CC 工作流、窗格→会话 ID 映射
references/json-session.mdsession、window、tab、screen、scrollback、inject 的 --json 模式
references/json-tmux-app.mdtmux、应用对话框、首选项、错误的 --json 模式

REPL 模式

不带参数运行会进入交互式 REPL，在命令之间保持上下文：

cli-anything-iterm2

评论

支持 Markdown