The gmux field guide

01 · the pane grid

Agents live in panes

The main surface is a grid of agent cards. Each card is a real terminal pane running a real agent process — plus a summary layer: a state chip, an activity sparkline, and a stop button. The grid is the fleet.

Reading a card

1. Header — the agent's name and its pane id. Grab the header (or the dotted handle) and drag to reorder the grid; the arrangement sticks for the session.
2. Pane id (v4-N) — the prefix is the grid's pane-protocol generation, the number is the pane's slot as it spawned: v4-1, v4-2, v4-3… Ids are how the rest of the system (links, the phone, the API) refers to a pane.
3. State chip — working is running, waiting wants you (a permission prompt or input), idle is parked and quiet.
4. Sparkline — recent output activity per card, so a busy fleet reads at a glance.
5. Stop button — the clay ⏹ circle halts that agent (it sends an interrupt, same as Esc).

02 · spawning agents

The composer: spawn anything

Spawning lives in the chat composer on the right — a pill with a mic, a text area, and a circular send button. Press N (or click the NEW pill) and fill in the four choices below.

The four choices

1. Agent type — what runs inside the pane:

Type	What it is
gagent	gmux's native GLM agent — the default, and the most integrated
claude	Claude Code, driven directly through its CLI
codex	OpenAI Codex CLI
qalcode	QalCode 2, the house coding agent
opencode / gemini / cursor / aider	other CLIs, wrapped the same way
terminal	a plain shell pane — no agent, just a terminal

2. Model — the picker groups cloud and local: zai/glm-5.3, zai/glm-5.3-flash, zai/glm-4.7… plus a Local (Ollama) group with ornith-1.5-35b, ornith-1.5-9b, glm-4.7-flash and qwen3.8. Local models need zero network.
3. Permission mode — 🔒 safe double-checks anything risky, default shows normal permission prompts, ⚡ yolo auto-approves. Pick per-agent, per-task.
4. Directory — which working folder the agent starts in. Restore-respawn remembers it (see Sessions).

Slash commands work right in the composer: type / and the command list opens; keep typing to filter, Enter to run.

03 · talking to agents

Enter sends. Esc stops. Mid-run words steer.

The composer is a conversation, not a form. Everything about driving a running agent is three keys deep.

Key	What it does
Enter	sends the message to the selected agent
Shift+Enter	newline — keep drafting
↑ / ↓	cycle through your prompt history
Esc (on empty input)	interrupt the running agent — a red flash and ⏹ stopped — sent Esc to <name> confirms it
⏹ click	the composer's stop circle does exactly the same interrupt
/	slash commands, filtered as you type

Steering mid-run

You don't wait for a turn to end. Type while the agent works and the message lands in its stream as a marked line — on the desktop it shows as [STEERING from you] …; from the phone it arrives the same way. The agent treats it as course-correction for the task it's already doing, not a new instruction.

The approval bar

When an agent hits a permission prompt (in default mode, say), an approval bar appears over the pane — mirrored on the phone. Resolve it from the keyboard: Enter to approve this one, D to deny, A to allow for the rest of the session.

04 · agent links (council)

Put two agents in a room

A link wires two panes into a standing conversation: whenever one settles a turn, the result relays to the other automatically. It's gmux's council pattern — agents conferring without you ferrying copy-paste between them.

How to link

1. Click the ⛓ link chip on the grid toolbar — the grid enters link mode.
2. Click the first pane, then the second. An SVG edge with two opposing arrows joins them.
3. Work as normal. Each settled turn is relayed into the peer's stream as [LINK from v4-N] …, and the reply comes back the same way.
4. Click the ✕ on the edge to unlink. Nothing is lost — both panes keep their history.

Why you'd want this

The classic pairing: a local personality model (say, ornith on Ollama — free, offline, always awake) strategising with the orchestrator that actually spawns sub-agents. The strategist thinks out loud; the orchestrator turns the good parts into real work. Reviewer-and-writer is the other staple.

05 · the phone companion

The fleet, in your pocket

gmux ships a small bridge that serves a PWA for your phone: watch the pane grid, send and steer messages, approve permission prompts, spawn and kill agents. Over Tailscale it works from anywhere — the desk and the pocket see the same state.

Pair your phone

1. Start the bridge on the desktop:

   $ ./phone/bridge/start_bridge.sh
   # pairing material (QR JSON) can be printed any time:
   $ python3 phone/bridge/bridge.py --pair

2. On the phone, open http://<host>:6302/app/ — the PWA loads from the bridge itself.
3. In the app: Settings → Pair.
4. Enter the 8-digit code (or scan the QR). The redeem call is a plain HTTP POST:

   $ curl -X POST http://<host>:6302/api/pair_code/redeem \
       -H 'Content-Type: application/json' \
       -d '{"code":"48219036"}'

06 · the model fleet & offline

Cloud when you have it. Local when you don't.

gmux talks to z.ai's GLM cloud (glm-5.3, glm-5.3-flash, glm-4.7…) and to local models through Ollama — ornith-1.5-35b/9b, glm-4.7-flash, qwen3.8 — with an automatic fallback chain between the two.

Two fleets, one picker

• Cloud (z.ai) — glm-5.3 for the hard thinking, glm-5.3-flash for the daily grind. A key pool with rotation spreads the load across keys.
• Local (Ollama) — ornith-1.5-35b:32k and ornith-1.5-9b:32k, glm-4.7-flash:32k, qwen3.8:32k. If Ollama runs, these work with the cable pulled.
• Fallback — when the cloud tier can't be reached, requests walk the local chain automatically. Same agent, same pane, quieter model.
• Hard offline — GMUX_OFFLINE=1 refuses cloud models at resolve time. No accidental requests, ever.

$ GMUX_OFFLINE=1 ./target/release/gmux6   # hard offline: cloud adapters refuse at the door
$ ollama serve                             # locals need Ollama up
$ ollama pull ornith-1.5-9b:32k

This is the offline-first philosophy: the desk keeps working when the internet doesn't. Local models carry planning, triage and personality roles indefinitely; the cloud is an upgrade, not a dependency. Everything else in gmux — panes, links, the phone, sessions — runs on your hardware either way.

07 · gestures (opt-in)

Hands on the fleet — if you ask for it

gmux can watch your hand through the camera and turn gestures into fleet control: dwell on a pane to focus it, a pinch to jump to the next waiting agent, a thumbs-up to approve. It is off by default and the camera is never touched until you opt in.

Turning it on

1. Open Options and enable 📷 Allow camera (gesture control) — it's off by default, and nothing camera-shaped powers up before this.
2. Toggle gesture mode any time with G. A small picture-in-picture overlay shows what the tracker sees and which gesture it currently reads.
3. Use the basics: dwell — hold your hand over a target to click it; pinch — jump to the next waiting / permission agent; thumbs-up — approve the current prompt.

08 · sessions & restore

Nothing evaporates

Every agent conversation is persisted as a JSONL transcript — one JSON object per line, turns and tool calls included — arranged as a tree you can branch. If the app (or the machine) goes down, relaunching offers to restore the agents that were running.

How it behaves

1. While you work — transcripts are written as the fleet talks. Agents can branch a conversation to retry a turn without torching the original.
2. On relaunch — gmux notices agents that were alive when it closed and offers to restore them.
3. Restore-respawn — the agent is respawned with its original working directory and model, and handed its transcript as context. Same desk, same desk-mates.

09 · power tools

Shortcuts, sockets, and a governor

Under the glass: a keyboard-first surface, a local HTTP API, an MCP server so other tools can drive gmux, and a monitor that keeps the fleet honest about rate limits.

Common shortcuts

Key	Action
N	open the composer / new-agent flow
Ctrl/Cmd+N	full new-agent form
J	jump to the next waiting / permission agent
G	toggle gesture mode
← → ↑ ↓	move the pane selection
Enter	approve a permission prompt · open chat
↑ (composer)	cycle prompt history
Shift+Enter	newline in the composer
Esc (empty input)	interrupt the running agent
/ (composer)	slash commands

Sockets other tools can use

• HTTP API on :6310 — an embedded axum server (bound to 127.0.0.1; move it with GMUX_API_PORT) exposing health, spawn, kill, steer and more:

$ curl :6310/api/health
$ curl -X POST :6310/api/agent/spawn \
    -H 'Content-Type: application/json' \
    -d '{"agent_type":"gagent","model":"ollama/ornith-1.5-9b:32k"}'

• MCP server — gmux ships an MCP backend (backend/mcp/gmux_mcp.py), so MCP-capable assistants and editors can list panes, spawn agents and steer them as tools.
• Agent monitor + governor — the monitor watches the fleet's health and output; when a provider starts pushing back (rate limits), the governor throttles — pausing or slowing spawns — instead of letting the whole fleet trip over the same wall.