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.

Table of Contents

• Quick Start
• Core Concepts
• Typical Workflow
• Features
• Installation
• Usage
• Configuration
• Supported Agents
• Architecture
• Contributing

Quick Start

Prerequisites

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

Launch

Run Flowmux in the repository or workspace where you want agents to work:

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

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

Features

• 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

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

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

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
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)
claude_hook_server_port = 15100

# External git viewer command (optional)
# 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"]

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

Supported Agents

• OpenCode
• Claude Code
• Codex

Flowmux auto-detects installed agent CLIs and enables discovered agents by default unless enabled_agents is set in global config.

Architecture

See ARCHITECTURE.md for technical details.

Core stack:

• Rust with Ratatui
• Tokio
• tmux
• libghostty-vt
• git2

Contributing

Before opening a PR, run:

cargo build --locked
cargo test

Follow Conventional Commit-style subjects such as feat(ui): improve dashboard navigation.