matchblox

module

v0.17.0 Latest Latest Go to latest Published: Oct 22, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/blox-eng/matchblox

Links

Open Source Insights

README ¶

matchblox

A tool for modern software builders.

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

Quick start

Install:
```
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.
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.
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.
Answer without leaving: a opens the conversation with the selected agent, in the right pane where there is one, else a peek at the bottom of a phone. When it asks with its question tool, its options are there and a digit answers; an agent at work takes a message.
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. The new agent gets a handoff to read the working tree and carry on. matchblox switch does it from the shell.
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; 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.

Keys

Key	What it does
`↑` or `k`, `↓` or `j`	Selects a row.
`Enter`	The safe action: go to the agent's pane.
`a`	Answers the selected agent, or sends it a message.
`x`	The destructive action. It runs only after a typed `y`.
`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 phone: 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 twice to answer it or send it a message, Enter to go to its pane, A switch under it to give its seat to another agent; tap ◂ matchblox in the tmux status line (with set -g mouse on) to come back, 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 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

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
matchblox command Command matchblox is a terminal console for a machine that runs many AI coding agents: sessions by tmux pane, machine load, git, and what to do.	Command matchblox is a terminal console for a machine that runs many AI coding agents: sessions by tmux pane, machine load, git, and what to do.
internal
actions Package actions runs the steps of an action on the service host.	Package actions runs the steps of an action on the service host.
advice Package advice ranks what to do next.	Package advice ranks what to do next.
app Package app is the console: a Bubble Tea program that keeps a copy of the state the service sends and draws it.	Package app is the console: a Bubble Tea program that keeps a copy of the state the service sends and draws it.
config Package config loads the per-machine goals.	Package config loads the per-machine goals.
docscheck Package docscheck reads the keys and the commands that the README, the contributing guide and the docs name, so tests can hold them to the binary.	Package docscheck reads the keys and the commands that the README, the contributing guide and the docs name, so tests can hold them to the binary.
doors Package doors is the setup a builder walks through in the console: one row for each step, each with one action.	Package doors is the setup a builder walks through in the console: one row for each step, each with one action.
gitscan Package gitscan reports on the checkouts agents work in: dirty paths, how far the default branch is behind its remote, and which worktrees are safe to remove.	Package gitscan reports on the checkouts agents work in: dirty paths, how far the default branch is behind its remote, and which worktrees are safe to remove.
history Package history keeps machine trends across restarts: an append-only CSV the console writes, plus any other CSV with a ts column to read alongside.	Package history keeps machine trends across restarts: an append-only CSV the console writes, plus any other CSV with a ts column to read alongside.
holds Package holds keeps the sessions nothing may type into: parked by the builder, or held by the stoker.	Package holds keeps the sessions nothing may type into: parked by the builder, or held by the stoker.
hooks Package hooks reads the events a coding agent sends through its hooks (`matchblox hook <event>`), and keeps them in a spool while no service listens.	Package hooks reads the events a coding agent sends through its hooks (`matchblox hook <event>`), and keeps them in a spool while no service listens.
host Package host reads the machine through gopsutil, for systems without a Linux /proc (macOS, Windows).	Package host reads the machine through gopsutil, for systems without a Linux /proc (macOS, Windows).
hosts Package hosts is the list of hosts a console opens: one on each line of ~/.config/matchblox/hosts, "#" starts a comment.	Package hosts is the list of hosts a console opens: one on each line of ~/.config/matchblox/hosts, "#" starts a comment.
idle Package idle says why a quiet session is idle, in the few words its row shows.	Package idle says why a quiet session is idle, in the few words its row shows.
limits Package limits reads the plan limits of each account an agent runs under, says them as /usage does (the percent of each window used), and forecasts whether the week lasts.	Package limits reads the plan limits of each account an agent runs under, says them as /usage does (the percent of each window used), and forecasts whether the week lasts.
pair Package pair is the contract between `matchblox pair` and the phone: the payload in the QR code, the request and reply lines, and the one-time key.	Package pair is the contract between `matchblox pair` and the phone: the payload in the QR code, the request and reply lines, and the one-time key.
panes Package panes builds the tmux steps that type into a pane.	Package panes builds the tmux steps that type into a pane.
procfs Package procfs reads the Linux /proc files the console needs, rooted at a configurable directory so tests can run against fixtures.	Package procfs reads the Linux /proc files the console needs, rooted at a configurable directory so tests can run against fixtures.
proto Package proto is the wire between the service and a console: one JSON envelope on each line, hello first from each side.	Package proto is the wire between the service and a console: one JSON envelope on each line, hello first from each side.
queue Package queue is the list of sessions that wait for the person, oldest first.	Package queue is the list of sessions that wait for the person, oldest first.
release Package release tests the release scripts: www/install.sh and the scripts under .github/scripts that make a release.	Package release tests the release scripts: www/install.sh and the scripts under .github/scripts that make a release.
remote Package remote reaches the service of another host over SSH: the console there speaks the same wire as a local one, on the stdin and stdout of `matchblox serve --stdio`.	Package remote reaches the service of another host over SSH: the console there speaks the same wire as a local one, on the stdin and stdout of `matchblox serve --stdio`.
replay Package replay turns frames of the console into the files the site and the README play: JSON frames, an animated SVG, and one still frame.	Package replay turns frames of the console into the files the site and the README play: JSON frames, an animated SVG, and one still frame.
said Package said reads what a coding agent said last, from its screen or its reply: the line to show, and whether it asks the person something.	Package said reads what a coding agent said last, from its screen or its reply: the line to show, and whether it asks the person something.
sample Package sample turns /proc, tmux and agent session files into Snapshots.	Package sample turns /proc, tmux and agent session files into Snapshots.
service Package service owns every loop, the state and the event stream.	Package service owns every loop, the state and the event stream.
setup Package setup finds the doors of this machine and opens them: it shows each change as an exact diff, writes it after a confirm, keeps a backup, and refuses when the file changed after the preview.	Package setup finds the doors of this machine and opens them: it shows each change as an exact diff, writes it after a confirm, keeps a backup, and refuses when the file changed after the preview.
ships Package ships follows the pull requests sessions drive: found in each session's own transcript, read on GitHub through CI to live.	Package ships follows the pull requests sessions drive: found in each session's own transcript, read on GitHub through CI to live.
state Package state is the snapshot file a running console leaves behind so an agent can read the same facts without sampling again.	Package state is the snapshot file a running console leaves behind so an agent can read the same facts without sampling again.
stoker Package stoker keeps the fires lit while the builder is away: rule steps that need no person and no model of their own.	Package stoker keeps the fires lit while the builder is away: rule steps that need no person and no model of their own.
tmuxtest Package tmuxtest gives tests tmux servers of their own: a socket name no builder uses, and a cleanup that ends the server and removes its socket, so no test leaves one behind.	Package tmuxtest gives tests tmux servers of their own: a socket name no builder uses, and a cleanup that ends the server and removes its socket, so no test leaves one behind.
transport Package transport carries proto messages: a local socket, or stdio when the console reaches the host over SSH.	Package transport carries proto messages: a local socket, or stdio when the console reaches the host over SSH.