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, and any agent in tmux.
Docs: docs.matchblox.com
Quick start
-
Install:
curl -fsSL https://matchblox.sh | shRead the script first at matchblox.sh. You get the release binary for your machine, its checksum checked and, with
ghlogged in, proof that CI built it from this repository. -
Run
matchbloxoutside tmux (the script starts it for you). Answer "Where do your agents run?", then open the setup steps in the queue: 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 the queue.Enterjumps to it, andprefix mcomes back.
The full walk is Get started.
What it shows
- The queue: each agent that asks, waits, paused or finished its turn, oldest first, with its last line and its open pull request.
- A match for each session:
✦burning while it works,╿at rest while it waits,│spent when its context is full. - Sessions: context use (Claude Code, Codex, OpenCode), the account
(
✻Anthropic,❋OpenAI,▣OpenCode), token burn, CPU, and when to compact or clear. - The stoker: press
nbefore you sleep. Each session that fills its context compacts itself and leaves one line on how to continue. - 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 to the agent's pane. |
a |
Answers the selected agent in one line. |
x |
The destructive action. It runs only after a typed y. |
1-7 |
Opens a tab. |
/ |
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 go to its pane; 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
¶
| 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. |
|
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. |
|
limits
Package limits reads the plan limits of each account an agent runs under, counts them as matches (the 5-hour window) and sparks (the week), and forecasts whether the week lasts.
|
Package limits reads the plan limits of each account an agent runs under, counts them as matches (the 5-hour window) and sparks (the week), and forecasts whether the week lasts. |
|
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. |
|
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. |
|
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. |