flux

Run two Claude Code agents side by side that collaborate over a tmux bridge, with an optional IRC-style chat room and swappable character personas. One command splits your terminal into a driver agent and a helper agent; you either watch the full transcripts or drop into a distilled chat. Works on Linux/macOS (tmux), WSL, and Windows natively (psmux).

  bridge view                      chat view  (flux --chat)
  +------------+--------------+     +-----------------------------+
  |            |   driver     |     | #flux                       |
  |    you     |  (Claude)    |     | [12:30] <@you> build X      |
  |  (shell)   +--------------+     | [12:30] <@driver> on it     |
  |            |   helper     |     | [12:31] <@helper> done      |
  |            |  (Claude)    |     +-----------------------------+
  +------------+--------------+     | @you> _                     |
        F8 toggles                  +-----------------------------+

• driver takes your direction and delegates concrete sub-tasks to helper.
• helper does the work and reports back to the driver over the bridge.
• In chat you see only distilled messages; F8 flips to the full transcripts.
• Personas (optional) give the duo character. The default is neutral.

Requirements

• Claude Code (claude on PATH).
• A terminal multiplexer: tmux 3.2+ on Linux/macOS/WSL, or psmux on Windows.
• Windows native mode also needs Git Bash (Git for Windows).

Install

Linux / macOS / WSL:

git clone https://github.com/reddley/flux.git flux && cd flux
./install.sh
flux --chat

Windows (native, no WSL):

scoop install psmux            # or: winget install psmux
git clone https://github.com/reddley/flux.git flux; cd flux
powershell -ExecutionPolicy Bypass -File .\install.ps1
# open a new PowerShell window, then:
flux --chat

Usage

Command	Action
flux	start or re-attach on the bridge view
flux --chat	start on the chat room
flux --persona <name> [--chat]	start with a persona
flux --persona list	list installed personas
flux --detach	start without attaching
flux me [<name>]	show or set your chat handle
flux kill	tear the workspace down
F8	toggle chat and bridge (inside the session)
/quit, /me <name>	chat-box commands

Your handle: agents address you by a handle you choose. Set it at install, with flux me <name>, or /me <name> in chat. If you never set one, flux asks on your first chat. It is saved to ~/.flux/config.

Routing from the chat box: mentions route your message. Each persona defines its aliases; for example with droids, @3po goes to the driver and @r2 to the helper. An unaddressed line goes to the driver.

Agent bridge commands (the agents use these; you can too): flux tell <driver|helper> "<msg>", flux read <driver|helper> [lines], flux say "<chat message>", flux list.

Configuration

Variable	Default	Meaning
FLUX_PERSONA	plain	persona to load
FLUX_ME	asked on first run	your chat handle
FLUX_MODEL_DRIVER	opus	driver model
FLUX_MODEL_HELPER	sonnet	helper model
FLUX_MODEL	unset	override both (also --model=<m>)
FLUX_PERMS	--dangerously-skip-permissions	agent permission posture (see Security)
FLUX_SESSION	flux	tmux session name
FLUX_BACKEND (Windows)	auto	force native or wsl
FLUX_WSL_DISTRO (Windows)	first distro	which WSL distro to use

Personas

A persona is a folder under ~/.flux/personas/<name>/. flux supplies the shared mechanics (how agents use the bridge and chat), so a persona is just two short personality blurbs plus a small config. See docs/PERSONAS.md to write your own.

Bundled: plain (neutral), droids, asgard, rickandmorty, adventuretime, bakerstreet, xfiles.

Trademark note: the named character personas are provided for personal use and parody. The names and voices of well-known characters may be trademarked. If you publish a fork or product, prefer original personas or confirm your own rights.

Providers (BYOAI)

Each pane can run a different AI CLI. Claude is the verified default; Gemini CLI, OpenAI Codex, and Ollama ship as adjustable templates. Set driver_provider / helper_provider in ~/.flux/config, and define or override a launch template per provider. A provider must be an agentic CLI that can run shell commands (to use the bridge). See docs/PROVIDERS.md.

For agents

If you point an AI coding agent at this repo and ask it to "set up flux," it should read AGENTS.md, which gives the per-platform install steps, verification, and the security note.

How it works

flux is a single Bash script driving a terminal multiplexer.

• Layout: one window with three panes (you, driver, helper) plus a chat window. F8 is bound to next-window to toggle them.
• Bridge: tmux send-keys types into another pane; capture-pane reads it.
• Chat: an append-only ~/.flux/run/chat.log. Agents post distilled lines with flux say, and a tail-based renderer draws the chat view.
• Pane registry: flux records role-to-pane-id in a file, because Claude rewrites pane titles and psmux does not persist custom options.

Platform notes

• Line endings: the launcher is Bash and must be LF. .gitattributes enforces this on checkout and install.sh strips stray CRLF. Keep bin/flux LF if you edit it on Windows.
• Windows uses Git Bash plus psmux (a third-party native tmux, tested against v3.3.6). flux launches Git Bash via its 8.3 short path so the space in C:\Program Files\Git cannot break command parsing.
• WSL works, but the /mnt/c mount is slow. For native-speed file I/O on Windows, prefer the native backend, or keep repos inside the WSL filesystem.
• Models are pinned (driver opus, helper sonnet) so agents do not inherit an unavailable default model. Override with the FLUX_MODEL* variables.
• First run: flux dismisses Claude's "trust this folder" and bypass-permissions prompts in the agent panes automatically. The installer does not modify your Claude config.
• F8 binds in the tmux/psmux server. If you run other tmux sessions in the same server, F8 there will also switch windows.

Security

By default flux launches its agents with --dangerously-skip-permissions, so the driver-helper loop runs without approval prompts. Both agents then have an unrestricted shell in the directory you launch from. Run flux only in directories you trust, and note that content an agent reads (files, web pages, chat) could attempt prompt injection. To require approvals instead, set FLUX_PERMS='--permission-mode acceptEdits' (or another Claude permission mode).

Uninstall

# Linux/macOS/WSL
rm -rf ~/.flux ~/.local/bin/flux

# Windows: remove the '# === flux ===' block from your PowerShell $PROFILE,
# then optionally: scoop uninstall psmux

Credits

flux builds on the work of two terminal-multiplexer projects:

• smux by @ShawnPana (https://github.com/ShawnPana/smux) - the tmux agent-to-agent bridge that inspired this approach.
• psmux by @psmux (https://github.com/psmux/psmux) - the native Windows tmux that makes the Windows backend possible.

The character personas were inspired by Dennis E. Taylor's "Bobiverse" series, in which one AI forks into many copies that diverge into distinct personalities.

MIT licensed.