Topics

#ai-agent-tools #ai-dashboard #ai-tools #flowmux #git-worktree #libghostty #multiplexer #parallel-coding #productivity #rust #session-management #terminal #terminal-workspace #tmux

Language breakdown

Rust 94.5%

Astro 2.3%

Shell 1.6%

CSS 1.2%

TypeScript 0.3%

JavaScript 0.0%

▸ Files click to expand

README

flowmux.dev

Where agent chaos becomes flow.

Flowmux

Flowmux is a terminal-native AI agent multiplexer for running, tracking, and switching between multiple CLI agents from one keyboard-first dashboard.

It is built for people who want fast hotkeys, a clean grid view of active work, tmux-backed persistence, and real terminal sessions instead of wrapped agent UIs.

Flowmux follows a simple Unix-style approach: it coordinates agent sessions, panes, projects, and worktrees while leaving your editor, git tools, shell, and terminal habits intact.

https://github.com/user-attachments/assets/66d88e2d-870b-44f4-8ca3-541fefa9ad51

Quick Start

Prerequisites

tmux
At least one supported agent CLI: opencode, claude, codex, or pi
Rust 1.90+, Zig 0.15.x, and git if building from source

Launch

Run Flowmux from your terminal:

flowmux

On first launch, Flowmux opens a tmux-backed dashboard where you can create agents, group them by project, and jump between running, waiting, and idle work without leaving the terminal.

Core Concepts

Projects. Projects are top-level dashboards. They let you separate work by repo, task, or stream and switch between them quickly.

Agents. Each agent runs in its own tmux pane, with its own working directory and optional git worktree.

Dashboard. The dashboard is the overview screen: a grid of agents with status, model information, and the latest response preview.

Agent View. Agent view shows the live terminal for one agent. Keys are forwarded to the pane, so you interact with the real CLI session.

Persistence. Flowmux stores session state and can reconnect to agents after tmux restarts, so long-running work is easier to resume.

Typical Workflow

Create a project if you want to separate this work from other dashboards.
Add one or more agents and optionally give them isolated git worktrees.
Monitor the grid to see which agents are running, waiting for input, or idle.
Use hotkeys to jump straight to the next running or waiting agent when attention is needed.
Open agent view when you want to read the full terminal, respond, inspect git state, or use a dedicated terminal in that working directory.
Reopen Flowmux later and continue from the saved session state.

Features

Simple Unix-style orchestration that keeps Flowmux focused on coordinating sessions instead of replacing your workflow
Bring your own tools: keep using your preferred editor, git UI, shell, terminal, and command-line utilities
Keyboard-first dashboard for managing multiple CLI agents from one terminal UI
Fast navigation between running, waiting, and idle agents
Project-based organization with per-agent working directories and optional git worktrees
Live agent terminals, plus quick access to a git viewer and a persistent shell in the agent directory
tmux-backed persistence with automatic session restoration after restarts
Response previews, model display, and status tracking in the grid view

Installation

Script

Install the latest Flowmux release on Linux or macOS with:

curl -fsSL https://raw.githubusercontent.com/grouzen/flowmux/main/install.sh | sh

Homebrew

On macOS, install Flowmux from the upstream tap with:

brew install --cask grouzen/tap/flowmux

From Source

Build the release binary with:

cargo build --release --locked

The binary will be available at target/release/flowmux.

libghostty-vt-sys statically builds the pinned Ghostty revision used by libghostty-vt. A default first build needs network access so Zig can fetch Ghostty build dependencies.

If you want a wrapper that reuses prefetched Ghostty inputs when present, use:

./tools/build-release-prefetched-libghostty-vt.sh

On macOS, to build one universal binary that runs on both Apple Silicon and Intel Macs, use:

./tools/build-universal-macos-prefetched-libghostty-vt.sh

If the required Rust macOS targets are not installed yet, the script installs aarch64-apple-darwin and x86_64-apple-darwin through rustup before building.

That writes the merged binary to target/universal2-apple-darwin/release/flowmux.

You can also install directly from the repo:

cargo install --path . --locked

GitHub Releases

Pre-compiled binaries for Linux and macOS are available on the Releases page.

Usage

Common Commands

# Launch with default tmux session name "flowmux"
flowmux
Launch with custom session name
flowmux --tmux-session my-session
Specify custom worktrees location
flowmux --git-worktrees-location /path/to/worktrees
Enable specific agents only
flowmux --enabled-agents opencode,claude,codex,pi

CLI Options

| Option | Default | Description | |--------|---------|-------------| | --tmux-session | flowmux | Name of the tmux session to use | | --git-worktrees-location | ~/.local/share/flowmux/worktrees | Base directory for git worktrees created by Flowmux | | --enabled-agents | (all discovered) | Comma-separated list of agent types to enable; overrides enabled_agents in global config |

Essential Keybindings

| Key | Action | |-----|--------| | n | Create new agent | | p | Create new project | | Enter | Open agent view | | Ctrl+g | Return to dashboard | | Ctrl+q | Jump to next running agent | | Ctrl+o | Jump to next waiting agent | | Ctrl+p | Jump to next idle agent | | Ctrl+v | Open configured git viewer | | Ctrl+t | Open persistent terminal in the agent directory | | Ctrl+b | Arm prefix mode so the next key is sent directly to the pane | | ? | Reopen the startup guide | | h/j/k/l or arrows | Move selection |

All other keys in agent, git viewer, and terminal views are forwarded to the active tmux pane.

Configuration

Global Configuration

Global config lives at ~/.config/flowmux/config.toml.

# Base port for Claude Code hook server (default: 15100)
claudehookserver_port = 15100
Base port for Pi extension callback server (default: 17100)
pihookserver_port = 17100
External git viewer command (optional)
Defaults to "git diff" when omitted or blank
Examples: "lazygit", "lazydiff diff"
git_viewer = "lazygit"
Whitelist of agent types to enable (optional)
When omitted, all discovered agents are available
enabled_agents = ["opencode", "claude", "codex", "pi"]

Per-Session Configuration

Per-session state is managed automatically under ~/.config/flowmux/sessions/<session>.toml. It stores the ordered project list and each agent's pane target, directory, project membership, and session metadata.

Example:

projects = ["Default", "work"]
[[agents]] name = "research" pane = "flowmux:1.0" directory = "/tmp/research" project = "work" agent_type = "opencode" port = 9000