matchblox

Light an idea. Keep it burning.

One terminal console for every AI coding agent you run in tmux. It shows which agent waits for you, what loads the machine, the state of every git checkout, and the one safe action that resolves each thing. It works on the host, over SSH, and from a phone.

Works with Claude Code, Codex, OpenCode, Cursor, and any agent in tmux.

Docs: docs.matchblox.com

On your phone: Matchblox Pocket runs the console on iPhone and iPad — pair with one scan, get a buzz when a session waits, and answer from anywhere. In beta on TestFlight.

Quick start

1. Install — with the script, Go, or Homebrew:

   curl -fsSL https://matchblox.sh | sh

   Read the script first at matchblox.sh. You get the release binary for your machine, its checksum checked and, with gh logged in, proof that CI built it from this repository. With Go, the same version builds from source:

   go install github.com/blox-eng/matchblox/cmd/matchblox@latest

   With Homebrew, on macOS or Linux:

   brew install blox-eng/tap/matchblox

   matchblox looks for a new release once a day and offers it in Sessions. [update] mode makes it install by itself, or never look: see Update.

2. Run matchblox outside tmux (the script starts it for you). Answer "Where do your agents run?", then open the setup steps in Sessions: tmux, the queue hooks, the way back.

3. In another terminal, start your agents in tmux, for example tmux new -s app claude. When an agent waits for you, it comes to the top of Sessions. Enter jumps to it, and prefix m comes back.

The full walk is Get started.

What it shows

• Sessions, grouped by need: who waits for you first (asks, waits, done), then who works, then who is quiet. A match for each: ✦ burning while it works, ╿ at rest, │ spent. Context use, the account, and when to compact or clear.
• Go straight in: Enter goes into the agent's own tmux pane, on this host or another, and moves only your screen. Sessions shows the selected agent's live screen, read-only, beside the list. ctrl+a m (your tmux prefix, then m) comes back, with the next waiting agent selected.
• Switch the agent, keep the seat: A runs another agent in the same pane (Claude Code, Codex, OpenCode or Cursor) with the session's name, directory and pull request, on the account you last started that agent on, else on default. The new agent gets saved handover evidence and a guide to its workspace and neighboring matches. Codex launches include workspace trust and workspace-write network access. matchblox switch does it from the shell.
• Get your agents back after tmux dies: while your agents run, the service records each one's conversation, tmux session, folder, branch and server. When the server dies, matchblox recover lists them, and matchblox recover --all reopens each conversation in its folder, waiting for you, with no duplicates.
• More than one sign-in: N starts Claude Code, Codex or Cursor on an account, a folder beside your default sign-in, or makes a new one: like your default, an empty one, or a copy of it that is cloned and its own, and a start says what stays shared with the default. You finish the sign-in in the session. N opens on the agent and the account you last started. Cursor accounts run on macOS only for now. Accounts.
• Start where you work: N starts an agent in a tmux session of its own. Its where offers your repositories: after one yes, matchblox finds the Git checkouts in your home folder, on this host only, and keeps the list fresh, and says which folders it skipped. matchblox scan does it from the shell. The list shows each repo with its worktrees and N live, the ones in use first. Paste a git URL in where and N clones it, then starts the agent there.
• Ships: every pull request your sessions drive, on one track from CI to live, said in words. One that waits for you merges after a typed y.
• The dock: what /usage says for each account, in percentages, each named by its provider (✻ Claude Team, ❋ OpenAI Team), with its logo in kitty and Ghostty; the machine; and the stoker. Press n before you sleep: each session that fills its context compacts itself and leaves one line on how to continue.
• Orders for the stoker: matchblox starts the stoker agent you choose out of sight, on a tmux server of its own. Say in your own words how to run the night ("merge them on green") and turn on the gos you give. It starts at once, keeps its own plan, follows your ways file and logs every step on a card. A merge, release or deploy you did not give waits on the card for your y, and what the stoker would wait for, matchblox fires itself.
• Three layouts, read from the screen's shape: one column on a phone, the list with a detail drawer on a phone held upright with a small font, and every column on a desk.
• Machine health, detached busy loops, git worktrees that are safe to remove, recommendations with their exact command, and 24 hours of history.

More in The console.

Keys

Key	What it does
↑ or k, ↓ or j	Selects a row.
Enter	The safe action: go into the selected agent's pane.
a	Goes into the pane, as Enter does.
x	The destructive action. It runs only after a typed y.
N	Starts a new session: where, the agent, its account and a first message (none on a new account).
A	Switches the selected session to another agent in the same pane.
1-7	Opens a tab: Sessions, Ships, Machine, Git, History, Panes, Stoker.
u	Cycles the dock of a narrow screen: usage, the machine, the stoker.
/	Searches the open tab.
f, n	The stoker on or off; a night that ends in the morning.
q	Quits. The service keeps running.

Every key: Keys.

From a phone

Set the startup snippet of your SSH app (Termius, for example) to matchblox, or run ssh -t ws-1 matchblox. The console is the first screen. Tap a row to see the agent's live screen, read-only. Tap it again to go into its pane. ‹ Sessions goes back. A switch under a row gives its seat to another agent. Tap ◂ matchblox in the tmux status line (with set -g mouse on) to come back from a pane, or press prefix m. See The phone.

Safety

Read-only by default. Every action shows its exact command before it runs. A destructive action needs x and then a typed y, and checks its facts again just before it runs. See Safety and SECURITY.md.

Config

matchblox works without a config. The first run writes ~/.config/matchblox/config.toml with goals for this machine and the agents it finds. Every known agent (Claude Code, Codex, OpenCode, Cursor, Gemini, aider, crush, qwen) is a session wherever it is installed; agents adds others. Every key is in config.example.toml and on Config.

Built on tmux

matchblox stands on tmux, and takes its model from it: a server that keeps running, and clients that attach from any terminal. See tmux, the engine.

Help

Questions: Discord. Bugs and ideas: GitHub issues.

Design

DESIGN.md is how matchblox looks, moves and speaks: the match, colour, motion, layout and copy. design/ holds the specs and plans. CONTRIBUTING.md · SECURITY.md · CHANGELOG.md

Light the match. Keep it burning.

matchblox.com · MIT · From Blox Engineering