跳到内容
PaneflowPaneflow

功能

并行运行编码智能体、保持终端会话运行、查看差异、编辑文件,并通过 Git worktree、MCP 和 Paneflow CLI 协调面板。

Paneflow 是面向编码智能体的原生终端复用器。并排运行智能体,返回会话,在同一窗口中查看或编辑它们的改动。Paneflow 在 Linux、macOS 和 Windows 上本地运行,是采用 GPL-3.0-or-later 许可证的免费开源软件。

首次安装时,请按照入门指南操作。

组织项目和面板

将项目作为 工作区 打开,用 标签页 组织任务。每个标签页包含运行智能体、shell 或命令的 面板。多个智能体可以共享标签页和检出目录。当任务需要独立的文件和分支时,创建单独的 Git worktree。

使用 Cmd/Ctrl+Shift+D 水平分屏,使用 Cmd/Ctrl+Shift+E 垂直分屏。每个新面板都在相同工作目录中启动 shell。用 Alt+Arrow 在面板之间切换,用 Cmd/Ctrl+Shift+N 打开另一个工作区。在 macOS 上使用 Cmd,在 Linux 和 Windows 上使用 Ctrl。

使用四种布局预设排列面板。快捷键和操作介绍键盘导航和自定义按键绑定。

拖动 Workspaces 侧边栏的右边缘,可将宽度设为 240 到 480 px 之间。默认宽度 432 px 是拖动中的一个卡位:边缘会在此停住,双击边缘即可回到该宽度。Paneflow 会在重启后保留宽度;窗口较窄时会限制侧边栏宽度,为面板留出空间。

将工作区归入 空间,例如一个用于工作,一个用于个人项目。创建空间后,侧边栏顶部会用活动空间的圆形图标和名称取代 Workspaces。圆形图标显示空间的图片;没有图片时显示其颜色的渐变,在所有主题中看起来都一样;没有颜色时只显示轮廓。Default 有自己的渐变。点击名称会打开空间菜单: Default、按 paneflow.json 中的顺序排列的各个空间、New space… 和 Manage spaces。此后,侧边栏、Cmd/Ctrl+1 到 Cmd/Ctrl+9 以及 Next workspace 都只作用于活动空间,每个空间会记住它上次显示的工作区。可以从菜单切换空间,也可以在 macOS 上用 Cmd+Alt+Left 和 Cmd+Alt+Right,在 Linux 和 Windows 上用 Ctrl+Alt+PageUp 和 Ctrl+Alt+PageDown。右键点击工作区并选择 Move to space,即可把它移到其他空间;确认移动的提示消息中的 Show 会切换到该空间。在 Settings > Spaces 中重命名空间、为其设置图片、颜色或独立的环境,以及删除空间。空间用于组织工作区,而不是隔离它们;没有任何空间时,Paneflow 的外观与以前完全相同。

隐藏的空间永远不会藏起需要你处理的智能体。此时,空间名称旁的按钮会显示所有隐藏空间中最紧急的状态:智能体等待输入或写入批准,或程序声明 blocked 时,显示琥珀色铃铛;没有智能体的程序声明 OSC 7501 error 时,显示带叉的红色圆圈;智能体在你离开期间完成时,显示蓝点。数量超过 1 时会显示总数,工具提示会注明目标,例如 Go to Work: 2 agents waiting for input。点击按钮会打开正在等待或失败的面板;对于未查看的完成,则打开发生完成的工作区。空间菜单以同样的方式标记每个隐藏空间。已静音工作区中已完成的智能体不计入,与通知的处理方式一致。桌面通知会注明每个智能体所在的空间。

运行智能体并跟踪活动

启动已安装的 Claude Code、Codex、OpenCode、Gemini、Pi、Hermes 或其他 CLI 智能体。每个智能体在普通终端中运行,并连接到自己的模型提供商。您可以读取输出、中断进程或用键盘接管。编码任务可以使用项目会话,项目外的研究和规划可以从主目录(~)打开智能体聊天。

智能体通过下文介绍的 OSC 7501 序列报告工作中、等待输入、已完成或出错等状态, Paneflow 会如实显示该状态。Claude Code 和 Codex 的生命周期 hooks 让 Paneflow 能够恢复它们的对话并为它们的标签页命名。每台机器只需安装一次:运行 paneflow integrations install claude-code 或 paneflow integrations install codex。Codex 会通过 /hooks 要求确认是否信任这些 hooks。也可以在智能体设置中打开某个智能体的 Paneflow hooks 开关。同一命令还会注册 Paneflow MCP 桥接,并为 Claude Code 安装 conductor skill。属于另一个 Paneflow home 的条目(例如与正式版并存的调试构建,或第二个 PANEFLOW_HOME)不会被改动:命令会列出两个 home,--force 可接管该条目。

未通过 OSC 7501 报告的智能体仍会根据其进程被检测到,但不会显示 turn 状态: Paneflow 从不根据屏幕内容猜测状态。即使窗口已关闭,也可以用 paneflow sessions 读取会话状态。自动化指南介绍 hooks 和事件。关于 OSC 7501 的技术文章跟随一个状态从智能体走到侧边栏。

侧边栏底部的 Agents 区域按状态分组列出活动空间中的智能体会话,最紧急的排在最前: Need you(等待输入)、Error、Done(已完成但结果尚未查看)、Working、Idle,最后是不报告状态的智能体所在的 No status。每个分组标题显示其中的智能体数量,没有任何智能体处于的状态不会形成分组。每个条目只占一行:智能体的标志、标签页标题、工作区名称和状态。同一分组中,最近的智能体排在最前。点击一行即可打开该智能体的面板;打开已完成智能体的标签页后,其结果会标记为已查看,并从 Done 移到 Idle。 3 秒后仍未通过 OSC 7501 报告任何内容的智能体会移到 No status;如果 Paneflow 知道首个报告状态的版本,工具提示会注明该版本,例如 Claude Code 2.1.295。 Cmd/Ctrl+Shift+J 按相同顺序在所有工作区中依次跳到等待输入的智能体、出错的智能体和未查看的结果。

点击 Agents 标题可以折叠该区域。拖动其上边缘可调整高度;也可以在已聚焦的侧边栏中按 Tab 移到该边缘,再使用方向键、Home、End 和 Enter(恢复为内容高度)。 Paneflow 会在重启后保留高度和折叠状态。按 Cmd/Ctrl+Alt+S 后,侧边栏的键盘光标会从树的最后一行继续进入该区域,并跳过分组标题在智能体之间逐个移动,按 Enter 打开智能体的面板。可以通过 Customize sidebar > Show > Agents 或 sidebar_show.agents 隐藏该区域。标题右侧的按钮会打开 Customize agent rows,可以显示或隐藏每一行的标志和工作区名称,设置保存在 sidebar_show.agent_logo 和 sidebar_show.agent_workspace 中。每一行始终显示其状态。

该区域列出活动空间的智能体。创建空间后,Customize agent rows > All spaces (sidebar_show.agent_all_spaces,默认关闭)会加入其他空间的智能体:在每个状态分组中,它们排在活动空间的智能体之后,并在工作区名称后注明所属空间。点击其中一个会切换到它所在的空间。

智能体工作时,其标题变为灰色,并有一道亮带扫过。可以通过 Customize sidebar > Show > Shimmer (sidebar_show.shimmer)为标签页行关闭该效果,通过 Customize agent rows > Shimmer (sidebar_show.agent_shimmer)为 Agents 区域关闭该效果:标题随后保持静止并使用常规颜色,旁边的工作动画仍然保留。

树中的工作区行和标签页行显示与 Agents 区域相同的状态。若要每个状态只看到一次,请关闭 Customize sidebar > Show > Status,或将 sidebar_show.status 设为 false:树中的行随后不再显示状态徽标和工作动画,标签页的 pull request 会占据其位置。当 Agents 区域折叠或隐藏时,树中的行会重新显示状态,因此你不会丢失状态信息。 Agents 区域、Cmd/Ctrl+Shift+J、面板标题栏和通知不受影响。

若要按智能体的状态而不是按项目列出标签页,请选择 Customize sidebar > Group by > Status,在命令面板中运行 Group the sidebar by status,或将 sidebar_group_by 设为 status。此时,活动空间中所有工作区的标签页会排在 Agents 区域的分组标题下:Need you、Error、Done、Working 和 Idle,每个标题显示其中的标签页数量。标签页采用其中最紧急的智能体的状态,没有运行智能体时为 Idle,并在标题后注明所属工作区。按状态分组时,侧边栏会隐藏 Agents 区域,以免同一批智能体列出两次,并在 New workspace 后显示 New tab 按钮:它会询问在哪个工作区中打开标签页;如果该空间只有一个工作区,则直接打开。拖动排序和工作区菜单仅在默认的 Folder 分组下可用。

在 Linux 和 macOS 上,启动器中的 Claude Code (team) 条目会启用 agent teams 来启动 Claude Code,并把每个队友打开在 lead 面板旁边各自的 Paneflow 面板中,而不是在 lead 的终端内。 Claude Code 通过 tmux 命令驱动这些面板,Paneflow 只为该面板自行应答这些命令:其他所有面板仍使用您真实的 tmux 和 PATH。一个团队只能打开、列出、重命名和关闭自己的面板。用 send-keys 向队友输入时,遵循与 paneflow send 相同的 PANEFLOW_IPC_SCRIPTING 规则。关闭 lead 的面板后,队友会作为普通面板保留。Windows 上没有这个条目: Claude Code 的终端团队模式在那里需要 tmux 和 POSIX shell,因此在 Windows 上队友在 lead 的面板内运行。

无论是不是智能体,任何程序都可以用 OSC 7501 序列声明自己的状态,例如构建、部署脚本或耗时较长的测试。面板标题栏会显示声明的状态。没有智能体的程序报告 blocked 或 error 时会计入该空间按钮,并发送一条注明面板名称的桌面通知,每个面板每 10 秒最多一条,前提是 agent_panel.notify_when_agent_waiting 允许。查看过该面板后,error 就不再计入,而标题栏会一直显示 error,直到你输入为止。对于智能体,声明的状态就是它的 turn 状态:blocked 和 error 会通知它需要你处理,一个 turn 之后的 done 会通知它已完成,声明的 error 会把它标记为出错。

printf '\033]7501;state=working:app=deploy\033\\'
if ./deploy.sh; then
  printf '\033]7501;state=done:app=deploy\033\\'
else
  printf '\033]7501;state=error:app=deploy\033\\'
fi

回到 shell 提示符时,working、blocked 和 idle 会被清除;done 和 error 会保留到你在面板中输入为止;state=clear 会清除状态。消息放在 base64 编码的 msg 字段中:msg=QXBwbHk/ 表示“Apply?”。Paneflow 从不根据声明的状态执行任何操作。

保持终端会话运行

退出 Paneflow 时,选择 Keep sessions running,让 shell 和智能体继续运行。重新打开应用即可连接到这些会话和终端画面。选择 Stop everything and quit 则会结束进程。

会话运行在独立的本地宿主进程中。只要宿主和机器仍在运行,会话就能保持活动。机器重启或宿主崩溃会结束进程。Paneflow 还会保存布局和工作目录。

当面板的会话在重启、宿主停止或宿主丢失后未能保留时,Paneflow 会恢复智能体正在进行的对话:在记录的文件夹中打开 shell,并输入智能体的恢复命令,例如 Claude Code 的 claude --resume <id>、Codex 的 codex resume <id>(会附加 -c check_for_update_on_startup=false),或 fx 的 fx --continue。 Paneflow 通过智能体的 SessionStart hook 记录对话,并在智能体结束或面板回到 shell 提示符时忘记它。如果文件夹已不存在,shell 会在您的主文件夹中打开,并显示 Folder not found: <path> 横幅。如果恢复在 15 秒内失败,Resume failed: <reason> 横幅会提供 New session。同一对话在多个面板中恢复时,只会在第一个面板中继续。如果只想重新打开 shell,请设置 "agents": {"restore_conversations": false};参见 agents 设置。

面板右键菜单和命令面板中的 Fork conversation 会在右侧的分割中打开 Claude Code 或 Codex 对话的一个分支。

一次点击即可关闭面板、标签页或工作区,并停止其中的会话:进程会结束,会话主机也会将其移除。如果标签页或工作区的差异面板中有未保存的文件,关闭前会先确认。

要一次关闭多个工作区或标签页,可以在 Workspaces 侧边栏中 Cmd/Ctrl+点击各行,将它们加入选择而不打开;或 Shift+点击,选中从上一个选中行到所点击行之间的全部行; Shift+Up 和 Shift+Down 可用键盘完成同样的操作。按 Delete 或 Backspace 可一起关闭已选中的行。右键点击已选中的行会打开一个菜单,其中有 Close 加所选内容(例如 Close 2 tabs)和 Clear selection。只选中一行时会直接关闭;选中两行或以上时,会先弹出对话框,列出将要关闭的内容以及将要停止的会话数量。选中的工作区会连同其所有标签页一起关闭。按 Escape 或普通点击会清除选择。

shell 或命令结束后,面板仍保持打开,以只读方式显示最终输出。选择 Restart 会打开新的 shell。要恢复智能体对话,请使用该智能体的会话命令;重启 shell 不会恢复对话。

关闭标签页后可以使用 Undo,或用 Cmd/Ctrl+Shift+T 重新打开最近关闭的标签页或面板。保留的会话仍可用时,Paneflow 会重新连接;否则会打开新的 shell。

查看和编辑改动

在活动标签页旁的停靠面板中打开 Changes,将检出目录与 HEAD 比较:可以使用标题栏右侧的切换按钮、Cmd/Ctrl+Alt+B,或命令面板中的 Toggle the Changes dock。停靠面板打开时会先显示其各个界面的列表,可以用 C、T 或 F,也可以用方向键选择。Changes 包含已暂存、未暂存的改动以及未跟踪文件。可以并排或统一查看差异,突出显示行内改动,并还原已修改文件中的单个区块。也可以清理或忽略空白字符。文件上方的一行工具栏包含分支、总 diffstat、刷新、全部折叠、 Unified 与 Split 切换、空白字符开关,以及已改动文件的文件树。每个文件标题会显示该文件是新增、修改、删除还是重命名,并附带完整路径和改动行数;文件滚动时,标题会固定在顶部。

打开 Files,以停靠面板的全宽浏览项目文件树。打开文件后,该标签页会显示文件,文件树移到文件右侧,可以拖动其左边缘或用方向键将其宽度调整为 160 到 560 px。 .env、.github/ 等点文件与其他条目一样显示;node_modules/、target/ 等被 git 忽略的条目以暗色显示,但仍可打开。工具栏包含 Refresh files、Search files (模糊匹配、不区分大小写,并遵循 .gitignore)以及 Expand all / Collapse all。文件树会定位到活动标签页的文件。右键点击条目可选择 Open with Default App、 Reveal in Finder(Windows 上为 Reveal in File Explorer,Linux 上为 Reveal in File Manager),以及 Open With 用 Paneflow 检测到的某个编辑器打开。

在终端或文本框之外按 Cmd/Ctrl+P,即可打开项目中的任意文件。文件查找器会列出最近打开的文件,最常用的排在最前;输入查询后,会以模糊匹配搜索整个项目,并遵循 .gitignore。所选文件会在停靠面板中打开。

文件标签页没有固定数量上限。右键点击标签页可选择 Copy Path、 Copy Relative Path、Close、Close Others、Close to the Right、 Close All 和 Reopen Closed Tab,后者会在原滚动位置重新打开最近关闭的 20 个文件之一。中键点击会关闭文件标签页;一次关闭多个标签页时,会保留 Changes 和 Terminal 标签页以及所有已修改的文件。停靠面板的标签页在重启后会恢复。文件上方的面包屑列出每一级文件夹:点击文件夹可在文件树中定位它,点击其箭头可浏览其中的内容。

在集成编辑器中修改代码:可以保存、撤销或重做。行旁的 Git 标记会打开弹窗,用于读取、复制或还原之前的文本。如果编辑期间磁盘上的文件发生变化,Paneflow 允许你解决保存冲突。在 macOS 上按 Cmd+F,在 Linux 和 Windows 上按 Ctrl+F,会在文件上方打开查找栏,提供 Match Case、Regular Expression 和 N of M 计数;按 Enter 和 Shift+Enter 在匹配项之间跳转。查找栏的箭头会展开 Replace 和 Replace All,后者只算一步撤销,并在正则模式下展开 $1;只读文件不提供替换。输入 :120 并按 Enter 可跳到第 120 行。Editor Controls 菜单顶部的 Word Wrap 会在当前标签页中折行显示长行,"editor": { "word_wrap": true } 则为新标签页启用折行。

停靠面板会按文件类型选择查看器:

文件查看器
PNG、JPEG、GIF、WebP、BMP、ICO、TIFF、SVG缩放范围 5% 到 800%,提供 Fit、Actual size,可用滚轮或拖动平移;图片最大 50 MB,每边最多 16,384 px。
CSV 和 TSV,最大 10 MB只读表格,表头固定并显示行号。Show source 会将其作为可编辑文本打开,该选择保存在 editor.csv_table 中。
MarkdownShow rendered markdown 和 Show markdown source,选择保存在 editor.markdown_rendered 中(默认显示源码)。渲染视图会跟随未保存的编辑。
Zip、jar、tar、tar.gz、tgz列出文件夹、大小和日期。不会解压任何内容。
10 MB 到 256 MB 的文本文件只读查看器,支持行号、选择和复制。

二进制文件、特殊文件或被拒绝预览的文件会显示 No preview for this file,附带其大小和原因,并提供 Open with Default App、定位操作和 Open With。

将文件和代码发送给智能体

在 Files 文件树中右键点击文件或文件标签页,选择 Send to Agent,即可在工作区中某个智能体的终端里输入该文件的路径并聚焦该终端,但不会按下 Enter:Claude Code、Codex 和 Gemini 使用 @path,其他智能体使用不带前缀的路径,路径相对于工作区根目录。有多个智能体时,该条目会按 Agents 区域的顺序打开列表;没有智能体时,该条目不可用,并显示 No agent in this workspace。把文件从文件树拖到智能体的终端上效果相同;拖到 shell 上则会插入加好引号的路径。

要针对代码给智能体留评论,将指针停在文件标签页的行号栏上,点击 + 评论一行,或拖动它评论一段范围。也可以右键点击选中内容,选择 Comment Selection(Cmd/Ctrl+Shift+M;未选中任何内容时评论光标所在行)。在行下方打开的区块中写下评论,然后用 Send to Agent (Cmd/Ctrl+Enter)将文件路径及其行范围、你的评论和引用的代码行粘贴到智能体的终端中,但不会提交。

在终端输出中 Cmd/Ctrl+点击路径,例如 src/main.rs:42:7,即可在停靠面板中打开该文件并定位到对应的行和列。如果相对路径在终端所在文件夹下不存在,Paneflow 会先从工作区根目录查找,再作为项目文件路径的结尾查找:terminal/view.rs:7 会打开 src-app/src/terminal/view.rs。有多个文件匹配时,点击会打开已填入该路径的文件查找器。点击时按住 Shift,或将 terminal.open_links_in 设为 external_editor,即可改用外部编辑器打开。Markdown 文件仍使用其查看器,已不存在的文件会显示 File not found。

随时查看项目上下文

分支显示和文件树跟随当前检出目录。可以复制绝对或相对路径用于提示词和命令。在终端中使用 Cmd/Ctrl+Shift+I,按名称查找文件,并插入按 shell 规则加好引号的路径。

工作区菜单和命令面板可以在 Zed、Cursor、VS Code 或 WebStorm 中打开工作区。 0.20.0 起,WebStorm 取代了 Windsurf:Paneflow 会在 PATH、JetBrains Toolbox 脚本文件夹以及标准和带版本号的安装位置中查找其启动器,最新版本优先,并在对应的行和列打开文件链接。设为 windsurf 的 external_editor 会回退到 auto。

粘贴图片会将它保存到 ~/.paneflow/cache/clipboard-images/ 并插入路径。 Claude Code 和 Codex 可以通过该路径附加图片。

Paneflow 将监听端口关联到运行对应进程的面板。识别出的开发服务器可以显示可点击的 URL。通过快捷键和操作,将常用的构建、测试、lint 或服务器命令固定为自定义按钮。

用 Git worktree 分开任务

并行任务需要独立检出目录时,可以使用 Git worktree。各目录可以有自己的分支、文件、面板和智能体会话,同时共享 Git 历史。worktree 是可选的:智能体也可以在同一检出目录中工作。

独立检出目录不能避免合并冲突,也不会隔离运行中的程序。 worktree 指南介绍创建、复用、清理,以及删除前对未提交文件创建快照的行为。

通过 MCP 共享面板输出

用 paneflow mcp install 为 Claude Code、Codex、Gemini CLI 或 OpenCode 安装本地 MCP 桥接。其 list_panes、read_pane 和 search_pane 工具让智能体读取其他面板的输出,无需您在对话之间复制终端历史。

输出作为不可信数据返回,由读取它的智能体分析。唯一的写入工具 write_pane 只有在您于 Paneflow 中允许这一对智能体会话之后,才会向另一个智能体的面板发送消息。桥接无法以任何其他方式发送按键或控制面板。参见 MCP 设置与行为。

通过 CLI 协调面板

使用本地 paneflow CLI 列出智能体、读取输出、等待结果或跟踪活动事件。启用对应权限后,脚本和智能体也可以创建或控制面板。

  • paneflow up 根据文件打开工作区,该文件定义面板、工作目录、命令和提示词。
  • paneflow flow run 执行 flow.toml 中定义的步骤,等待依赖或输出模式,并捕获结果。

paneflow send 预填文本。添加 --submit 才会明确按下 Enter。写入和提交需要对应权限;启动带有命令或提示词的面板也需要编排或脚本权限。 CLI 自动化指南介绍这些控制。

要读取智能体进度、发送提示词并等待报告,请按照 Conductor 指南操作。

按工作方式调整 Paneflow

通过设置选择 shell、主题、终端显示、快捷键、通知、工作区模板和智能体访问控制。许多更改可以在应用运行期间生效;新的默认 shell 会应用到新终端。

Settings > Appearance > Interface style 决定窗口的形态。Classic 自 0.20.0 起为默认值,窗口边到边铺满,顶部面板和 Changes 停靠面板的标签页位于标题栏中。Rounded 保留早期版本中浮动的面板卡片。用于选择 Themed、Mica 或 Blended 的设置现在名为 Background style,取值不变。同一页面还可以从 21 个图标中设置 App icon,以及设置 Workspace icon,即侧边栏中每个工作区前面的图标。参见外观设置。

基于文件的配置和高级选项见 paneflow.json 参考。安装、图形、shell 或字体问题见故障排除指南。