flowforge tui

flowforge tui launches the FlowForge controller — a full-screen terminal UI built with Bubble Tea — inside an active tmux session. The controller is the orchestration surface for v3.x workflows: it owns the Maestro session, manages worker tmux windows, and surfaces real-time status from the workers it spawned.

Synopsis

flowforge tui --project <name> [--session <tmux-session>]

--project is required. --session is optional.

Description

When you run flowforge tui the binary first verifies that the calling shell is inside a tmux session by checking the TMUX environment variable. Running outside tmux is a hard error: the controller spawns workers as new tmux windows and cannot do that without a host session. If TMUX is unset, the command fails with not inside a tmux session (TMUX env var is not set) and exits non-zero.

After the tmux precondition is satisfied, the binary captures the calling shell’s working directory with os.Getwd() and computes the target tmux session name. If --session was supplied it is sanitized to tmux-safe characters ([a-zA-Z0-9_-]); otherwise the binary derives a session name from --project via the manager’s SessionName helper, which prefixes flowforge- and applies the same sanitization. The binary then calls tmuxMgr.HasSession(name): if the session does not exist it is created with tmuxMgr.NewSession(project); if it already exists, the binary uses that name as the target for any worker windows it later spawns. Either way the Bubble Tea program runs in the calling shell’s existing tmux pane in alt-screen mode — the binary does not issue a tmux attach-session call.

Once tmux is ready the binary constructs three coupled subsystems: a tmux.Manager for window lifecycle, a tmux.Capture adapter for reading worker pane output, and a claude.SessionManager that brokers the Maestro session. These are passed into tui.NewApp along with the captured WorkDir, so any worker spawned later operates relative to wherever flowforge tui was invoked from. Run the command from your project root. The resulting Bubble Tea program runs until the user exits.

The TUI is the recommended way to interact with FlowForge v3 once a project is initialized. For routine slash-command invocation outside the controller, see flowforge run.

Arguments

None. The TUI takes its inputs from the flags below.

Options

Flag	Type	Default	Description
`--project`	string	(required)	Project name. Used to derive the tmux session name when `--session` is not provided, and surfaced throughout the controller UI.
`--session`	string	(empty)	Target tmux session name (used to host worker windows). If empty, the controller derives a session name from `--project` (`flowforge-<sanitized-project>`). The provided value is sanitized to tmux-safe characters before use. The controller creates this session if it does not exist and reuses it if it does.

Environment variables

Variable	Required	Purpose
`TMUX`	yes	Set automatically by tmux. The TUI refuses to start if this is unset.

The controller inherits the rest of the parent environment for use by its children.

Examples

Launch the TUI for a project named delphos from inside tmux:

tmux new -s work
# inside the tmux session:
flowforge tui --project delphos

The controller targets a tmux session named flowforge-delphos — creating it if it does not exist, or reusing it if it does. Worker windows appear as additional windows in that session.

Target a specific pre-existing tmux session by name:

flowforge tui --project delphos --session flowforge-delphos-staging

Run from a non-tmux shell (this fails on purpose):

$ flowforge tui --project demo
Error: not inside a tmux session (TMUX env var is not set)

The fix is to start tmux first (tmux new -s work) and re-run the command.

Exit codes

Code	Meaning
`0`	The TUI exited cleanly, typically because the user quit the controller.
Non-zero	A precondition or runtime error occurred. Common causes: missing `TMUX`, the working directory could not be determined, tmux session creation failed, or the Bubble Tea program returned an error. The first line of `stderr` names the failure mode.

flowforge install --global — bootstrap the FlowForge asset bundle before launching the controller.
flowforge register-repo — register your repository with the global install.
flowforge run — execute slash commands without the TUI.
flowforge worker — internal command spawned by the controller.
Maestro Pattern — the orchestration model the controller implements.
Sessions — how the controller maps to FlowForge sessions.