Skip to content
PaneflowPaneflow

Features

Run coding agents in parallel, keep terminal sessions running, review diffs, edit files, and coordinate panes with Git worktrees, MCP, and the Paneflow CLI.

Paneflow is a native terminal multiplexer for coding agents. Run agents side by side, return to their sessions, and review or edit their changes in the same window. It runs locally on Linux, macOS, and Windows and is free and open source under GPL-3.0-or-later.

For your first installation, follow the getting started guide.

Organize projects and panes

Open a project as a workspace and organize its tasks in tabs. Each tab contains panes where you can run agents, shells, or commands. Several agents can share a tab and the same checkout. Create a separate Git worktree when a task needs its own files and branch.

Split the focused pane horizontally with Cmd/Ctrl+Shift+D or vertically with Cmd/Ctrl+Shift+E. Each new pane starts a shell in the same working directory. Move between panes with Alt+Arrow and open another workspace with Cmd/Ctrl+Shift+N. Use Cmd on macOS and Ctrl on Linux and Windows.

Use the four layout presets to arrange panes. Consult shortcuts and actions for keyboard navigation and custom bindings.

Drag the right edge of the Workspaces sidebar to set its width between 240 and 480 px. The default width, 432 px, is a notch in the drag: the edge holds on it, and a double-click on the edge returns to it. Paneflow remembers the width across restarts, and a narrow window caps it so the panes keep their room.

Group workspaces into spaces, for example one for work and one for personal projects. Once you create a space, the top of the sidebar shows the active space's circle and name in place of Workspaces. The circle holds the space's image, or else its color as a gradient that looks the same in every theme, or else an outline; Default has a gradient of its own. Click the name to open the space menu: Default, your spaces in their paneflow.json order, New space…, and Manage spaces. The sidebar, Cmd/Ctrl+1 to Cmd/Ctrl+9, and Next workspace then only cover the active space, and each space remembers the workspace it last showed. Switch spaces from the menu, or with Cmd+Alt+Left and Cmd+Alt+Right on macOS, Ctrl+Alt+PageUp and Ctrl+Alt+PageDown on Linux and Windows. Right-click a workspace and choose Move to space to file it elsewhere; Show, in the toast that confirms the move, switches to that space. Rename spaces, give them an image, a color, or their own environment, and delete them in Settings > Spaces. A space organizes your workspaces; it does not isolate them, and without any space Paneflow looks exactly as before.

A hidden space never hides an agent that needs you. A button beside the space name then shows the most urgent state across the hidden spaces: an amber bell when an agent waits for input or a write approval, or a program declares blocked; a red crossed circle when a program without an agent declares an OSC 7501 error; a blue dot when an agent finished while you were elsewhere. The total appears once it exceeds 1, and the tooltip names the destination, for example Go to Work: 2 agents waiting for input. Clicking it opens the waiting or failed pane, or for an unseen finish, the workspace where it happened. The space menu marks each hidden space the same way. Finished agents of a muted workspace are left out, as they are from notifications. Desktop notifications name the space of each agent.

Run and follow coding agents

Launch Claude Code, Codex, OpenCode, Gemini, Pi, Hermes, or another CLI agent installed on your machine. Each agent runs in an ordinary terminal and connects to its own model provider. Read its output, interrupt it, or take over with the keyboard. Open project sessions for coding tasks, or an agent chat from your home directory (~) for research and planning outside a project.

An agent reports whether it is working, waiting for input, finished, or in an error state through the OSC 7501 sequence described below, and Paneflow shows exactly that. Lifecycle hooks for Claude Code and Codex let Paneflow resume their conversations and name their tabs. Install these once per machine with paneflow integrations install claude-code or paneflow integrations install codex. Codex asks you to trust the hooks through /hooks. You can also turn on the Paneflow hooks toggle of an agent in the agent settings. The same command registers the Paneflow MCP bridge and, for Claude Code, the conductor skill. An entry that another Paneflow home owns (a debug build next to a release, or a second PANEFLOW_HOME) is left alone: the command names both homes, and --force takes the entry over.

An agent that does not report through OSC 7501 is still detected from its process, but shows no turn status: Paneflow never guesses it from the screen. Use paneflow sessions to read session status even when the window is closed. The automation guide explains hooks and events. The OSC 7501 engineering post follows a status from the agent to the sidebar.

The Agents section at the bottom of the sidebar lists the agent sessions of the active space, grouped by status, most urgent first: Need you (waiting for input), Error, Done (finished with a result you have not seen yet), Working, Idle, then No status for agents that report none. Each group header shows how many agents it holds, and a status that no agent has gets no group. Each row fits on one line: the agent's logo, the tab title, the workspace name, and its status. Within a group, the most recent agent comes first. Click a row to open the agent's pane; opening a finished agent's tab marks its result as seen and moves it from Done to Idle. An agent that has reported nothing through OSC 7501 after 3 seconds moves to No status, and its tooltip names the first version that reports it when Paneflow knows it, for example Claude Code 2.1.295. Cmd/Ctrl+Shift+J goes through the agents waiting for input, then the failed ones, then the unseen results, in the same order, across every workspace.

Click the Agents header to collapse the section. Drag its top edge to resize it, or press Tab in the focused sidebar to reach that edge, then use the arrow keys, Home, End, and Enter, which returns to the content height. Paneflow remembers the height and the collapsed state across restarts. After Cmd/Ctrl+Alt+S, the sidebar's keyboard cursor continues from the last tree row into the section and steps from agent to agent past the group headers, and Enter opens the agent's pane. Hide the section from Customize sidebar > Show > Agents or with sidebar_show.agents. The button at the right of the header opens Customize agent rows, which shows or hides each row's logo and workspace name, stored in sidebar_show.agent_logo and sidebar_show.agent_workspace. A row always shows its status.

The section lists the active space's agents. Once you have declared a space, Customize agent rows > All spaces (sidebar_show.agent_all_spaces, off by default) adds the agents of your other spaces: in each status group they follow the active space's agents, and each one names its space after its workspace. Clicking one switches to its space.

While an agent works, its title turns gray and a bright band sweeps across it. Turn that off for tab rows with Customize sidebar > Show > Shimmer (sidebar_show.shimmer) and for the Agents section with Customize agent rows > Shimmer (sidebar_show.agent_shimmer): the title then stays still in its usual color, and the working animation next to it remains.

Workspace and tab rows in the tree show the same status as the Agents section. To see each status only once, turn off Customize sidebar > Show > Status or set sidebar_show.status to false: tree rows then drop their status badges and their working animation, and a tab's pull request takes their place. While the Agents section is folded or hidden, tree rows show their status again, so you never lose it. The Agents section, Cmd/Ctrl+Shift+J, the pane header, and notifications are unaffected.

To list your tabs by what their agents are doing rather than by project, choose Customize sidebar > Group by > Status, run Group the sidebar by status from the command palette, or set sidebar_group_by to status. The tabs of every workspace of the active space then sit under the headings of the Agents section, Need you, Error, Done, Working, and Idle, with the number of tabs in each. A tab takes the status of its most urgent agent, Idle when it runs none, and names its workspace after its title. Grouped by status, the sidebar hides the Agents section, which would list the same agents twice, and shows a New tab button after New workspace: it asks which workspace the tab opens in, or opens it at once when the space has a single workspace. Drag reordering and the workspace menu stay with the default Folder grouping.

On Linux and macOS, the Claude Code (team) launcher entry starts Claude Code with agent teams enabled and opens each teammate in its own Paneflow pane, next to the lead's pane, instead of inside the lead's terminal. Claude Code drives those panes through tmux commands, which Paneflow answers itself for that pane only: every other pane keeps your real tmux and PATH. A team can only open, list, rename, and close its own panes. Typing into a teammate with send-keys follows the same PANEFLOW_IPC_SCRIPTING rule as paneflow send. Closing the lead's pane leaves the teammates open as ordinary panes. The entry does not exist on Windows: Claude Code's terminal team mode needs tmux and a POSIX shell there, so on Windows teammates run inside the lead's pane.

Any program can also declare its own status with an OSC 7501 sequence, agent or not: a build, a deploy script, a long test run. The pane header shows the declared state. A program without an agent that reports blocked or error counts toward that space button and sends a desktop notification that names the pane, at most once every 10 seconds per pane, when agent_panel.notify_when_agent_waiting allows it. An error stops counting once you have looked at the pane, while the header keeps error until you type. For an agent, the declared status is its turn state: blocked and error notify that it needs you, done after a turn notifies that it finished, and a declared error marks it as errored.

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

working, blocked, and idle clear when the shell prompt returns, done and error stay until you type in the pane, and state=clear removes the status. A message goes in the base64-encoded msg field: msg=QXBwbHk/ reads "Apply?". Paneflow never acts on a declared status.

Keep terminal sessions running

When quitting Paneflow, choose Keep sessions running to leave shells and agents running. Reopen the app to reconnect to those sessions and their terminal screens. Choose Stop everything and quit to end the processes.

Sessions run in a separate local host process. They stay alive while that host and your machine remain running. A machine restart or host crash ends the processes. Paneflow also saves the layout and working directories.

When a pane's session did not survive a reboot, a host stop, or a lost host, Paneflow restores the conversation the agent was running: it opens a shell in the recorded folder and types the agent's resume command, such as claude --resume <id> for Claude Code, codex resume <id> for Codex (with -c check_for_update_on_startup=false added), or fx --continue for fx. Paneflow records the conversation from the agent's SessionStart hook and forgets it when the agent ends or the pane returns to its shell prompt. If the folder is gone, the shell opens in your home folder under a Folder not found: <path> banner. If the resume fails within 15 seconds, a Resume failed: <reason> banner offers New session. A conversation restored in several panes resumes only in the first. To only reopen the shell, set "agents": {"restore_conversations": false}; see the agents settings.

Fork conversation, in the pane context menu and the command palette, opens a branch of a Claude Code or Codex conversation in a split to the right.

Closing a pane, tab, or workspace takes one click and stops its sessions: their processes end and the session host forgets them. A tab or workspace whose diff dock holds unsaved files asks first.

To close several workspaces or tabs at once, Cmd/Ctrl+click rows in the Workspaces sidebar to add them to a selection without opening them, or Shift+click to select everything from the last one to the row you click; Shift+Up and Shift+Down do the same from the keyboard. Delete or Backspace closes the selected rows together. Right-click a selected row for a menu with Close followed by what is selected, such as Close 2 tabs, and Clear selection. A single selected row closes at once; with two or more, a dialog first lists what will close and how many sessions will stop. A selected workspace closes with all its tabs. Escape or a plain click clears the selection.

When a shell or command ends, its pane stays open with the final output in read-only mode. Choose Restart to open a new shell. To resume an agent conversation, use that agent's own session commands; restarting the shell does not resume the conversation.

Use Undo after closing a tab, or Cmd/Ctrl+Shift+T to reopen the most recently closed tab or pane. Paneflow reconnects to a retained session when available; otherwise, it opens a new shell.

Review and edit changes

Open Changes in the dock beside the active tab to compare the checkout with HEAD: use the toggle at the right of the title bar, Cmd/Ctrl+Alt+B, or Toggle the Changes dock in the command palette. The dock opens on a list of its surfaces, which you can pick with C, T, or F or with the arrow keys. Changes includes staged and unstaged changes and untracked files. Read split or unified diffs, highlight changes within lines, and revert individual blocks in modified files. You can also trim or ignore whitespace. One toolbar row above the files holds the branch, the total diffstat, refresh, collapse all, the Unified and Split switch, the whitespace toggle, and a tree of the changed files. Each file header shows whether the file was added, modified, deleted, or renamed, with its full path and its counts, and stays pinned while its file scrolls.

Open Files to browse the project tree at the full width of the dock. Opening a file replaces the tab with the file and moves the tree to its right, where its left edge or the arrow keys resize it between 160 and 560 px. Dot files such as .env and .github/ show like any other entry, and git-ignored entries such as node_modules/ and target/ show dimmed and still open. The toolbar holds Refresh files, Search files (a fuzzy, case-insensitive search that respects .gitignore), and Expand all / Collapse all. The tree reveals the file of the active tab. Right-click an entry for Open with Default App, Reveal in Finder (Reveal in File Explorer on Windows, Reveal in File Manager on Linux), and Open With one of the editors Paneflow detects.

Press Cmd/Ctrl+P outside a terminal or a text field to open any project file. The file finder lists the files you opened recently, most used first, and a query searches the whole project with fuzzy matching, respecting .gitignore. It opens the file you pick in the dock.

File tabs have no fixed limit. Right-click a tab for Copy Path, Copy Relative Path, Close, Close Others, Close to the Right, Close All, and Reopen Closed Tab, which brings back one of the last 20 closed files at its scroll position. A middle click closes a file tab, and closing several tabs at once keeps the Changes and Terminal tabs and every modified file. The dock's tabs come back after a restart. The breadcrumb above a file lists each folder: click one to reveal it in the tree, or its chevron to browse what it holds.

Edit code in the integrated editor: save changes, undo, or redo. Git markers beside the lines open a popup to read, copy, or revert the previous text. If a file changes on disk while you edit it, Paneflow lets you resolve the save conflict. Cmd+F on macOS, Ctrl+F on Linux and Windows, opens a find bar over the file with Match Case, Regular Expression, and an N of M count; Enter and Shift+Enter step through the matches. Its chevron opens Replace and Replace All, which is a single undo step and expands $1 in regex mode; read-only files have no replace. Type :120 and press Enter to jump to line 120. Word Wrap, at the top of the Editor Controls menu, folds long lines in that tab, and "editor": { "word_wrap": true } turns it on for new tabs.

The dock picks a viewer by file type:

FileViewer
PNG, JPEG, GIF, WebP, BMP, ICO, TIFF, SVGZoom from 5 % to 800 %, Fit, Actual size, and pan by wheel or drag, for images up to 50 MB and 16,384 px per side.
CSV and TSV, up to 10 MBA read-only table with a fixed header and line numbers. Show source opens it as editable text, and the choice is remembered in editor.csv_table.
MarkdownShow rendered markdown and Show markdown source, remembered in editor.markdown_rendered (source by default). The rendered view follows unsaved edits.
Zip, jar, tar, tar.gz, tgzA listing with folders, sizes, and dates. Nothing is extracted.
Text from 10 MB to 256 MBA read-only viewer with line numbers, selection, and copy.

A binary file, a special file, or a refused preview shows No preview for this file with its size and the reason, Open with Default App, the reveal action, and Open With.

Send files and code to an agent

Right-click a file in the Files tree or a file tab and choose Send to Agent to type its path in the terminal of an agent of the workspace and focus it, without pressing Enter: @path for Claude Code, Codex, and Gemini, the bare path for the other agents, relative to the workspace root. With several agents, the entry opens a list in the Agents order; with none, it is disabled and reads No agent in this workspace. Dragging a file from the tree onto an agent's terminal does the same, and onto a shell inserts the quoted path.

To comment on code for an agent, rest the pointer on the gutter of a file tab and click the + to comment a line, or drag it to comment a range. You can also right-click a selection and choose Comment Selection (Cmd/Ctrl+Shift+M, which comments the caret's line when nothing is selected). Write the comment in the block that opens under the lines, then Send to Agent (Cmd/Ctrl+Enter) pastes the file path with its line range, your comment, and the quoted lines into the agent's terminal, without submitting.

Cmd/Ctrl+click a path in terminal output, such as src/main.rs:42:7, to open the file in the dock at that line and column. A relative path that does not exist under the terminal's folder is looked up from the workspace root, then as the end of a project file path: terminal/view.rs:7 opens src-app/src/terminal/view.rs. When several files match, the click opens the file finder filled with the path. Hold Shift with the click, or set terminal.open_links_in to external_editor, to open the file in your external editor instead. Markdown files keep their viewer, and a file that no longer exists shows File not found.

Keep project context at hand

The branch display and file tree follow the active checkout. Copy absolute or relative file paths for prompts and commands. Use Cmd/Ctrl+Shift+I in a terminal to find a file by name and insert its path, quoted for the shell.

The workspace menu and the command palette open a workspace in Zed, Cursor, VS Code, or WebStorm. WebStorm replaces Windsurf in 0.20.0: Paneflow finds its launcher on PATH, in the JetBrains Toolbox scripts folder, and in standard and versioned installs, newest first, and opens a file link at its line and column. An external_editor set to windsurf falls back to auto.

Paste an image to save it under ~/.paneflow/cache/clipboard-images/ and insert its path. Claude Code and Codex can attach that path as an image.

Paneflow associates listening ports with the panes running their processes. Recognized development servers can show clickable URLs. Pin frequent build, test, lint, or server commands as custom buttons using shortcuts and actions.

Separate tasks with Git worktrees

Use a Git worktree when parallel tasks need separate checkouts. Each can have its own branch, files, panes, and agent sessions while sharing Git history. Worktrees are optional: agents can also work in the same checkout.

Separate checkouts do not prevent merge conflicts or isolate running programs. The worktree guide covers creation, reuse, cleanup, and snapshots of uncommitted files before removal.

Share pane output through MCP

Install the local MCP bridge with paneflow mcp install for Claude Code, Codex, Gemini CLI, or OpenCode. Its list_panes, read_pane, and search_pane tools let an agent read another pane's output without you copying terminal history between conversations.

Output is returned as untrusted data for the reading agent to analyze. Its one write tool, write_pane, sends a message to another agent's pane only after you allow that pair of agent sessions in Paneflow. The bridge cannot send keystrokes or control panes in any other way. See MCP setup and behavior.

Coordinate panes with the CLI

Use the local paneflow CLI to list agents, read output, wait for a result, or follow activity events. Scripts and agents can also create or control panes when the relevant permissions are enabled.

  • paneflow up opens a workspace from a file defining its panes, working directories, commands, and prompts.
  • paneflow flow run executes steps defined in flow.toml, waits for dependencies or output patterns, and captures results.

paneflow send prefills text. Add --submit to press Enter explicitly. Writing and submission require the corresponding permissions; launching panes with commands or prompts also requires an orchestration or scripting permission. The CLI automation guide explains these controls.

For a workflow that reads agent progress, sends a prompt, and waits for a report, follow the Conductor guide.

Adjust Paneflow to your workflow

Use Settings to choose the shell, theme, terminal display, shortcuts, notifications, workspace templates, and agent access controls. Many changes apply while the app is running; a new default shell applies to new terminals.

Settings > Appearance > Interface style chooses the shape of the window. Classic, the default since 0.20.0, lays the window out edge to edge, with the tabs of the top panes and of the Changes dock in the title bar. Rounded keeps the floating pane cards of earlier releases. The setting that picks Themed, Mica, or Blended is now named Background style and keeps its values. The same page sets the App icon, from twenty-one icons, and the Workspace icon, the glyph in front of each workspace in the sidebar. See appearance settings.

For file-based configuration and advanced options, use the paneflow.json reference. For installation, graphics, shell, or font problems, follow the troubleshooting guide.