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\\'
fiworking, 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:
| File | Viewer |
|---|---|
| PNG, JPEG, GIF, WebP, BMP, ICO, TIFF, SVG | Zoom 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 MB | A 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. |
| Markdown | Show 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, tgz | A listing with folders, sizes, and dates. Nothing is extracted. |
| Text from 10 MB to 256 MB | A 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 upopens a workspace from a file defining its panes, working directories, commands, and prompts.paneflow flow runexecutes steps defined inflow.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.