muxr

March 27, 2026~3 minArchived

Why I built this

Signal

I was running coding agents in tmux across many repositories, and the work outlived any one conversation: a campaign, with a note on what it was for and a log of where it stood. Its address lived in three places nothing kept in step: tmux, disk and the agent's conversation.

Build

A Rust binary that owned the address: one command created the tmux session, the campaign directory and the running agent together, a rename landed in all three, and a resume engine brought a session back after a reboot.

Novel

The resume engine was the part nothing else did. Recycle stopped guessing whether the agent was idle and waited for a sentinel file the agent writes once its flush is done. Session records became typed, so an unparseable file refuses a relaunch instead of quietly stripping a live session of its prompt.

Journey

We eventually went with herdr, a terminal workspace manager built for coding agents, and wrote herdr-estate as the campaign layer on top of it. The address and the campaign files carried over; the terminal half muxr had to own itself now belongs to herdr.

muxr was a session manager for coding agents, written in Rust over tmux. A session is a campaign addressed <repo>/<campaign>, and that address names three things: the tmux session, a directory holding campaign.md and log.md, and the runtime’s conversation (Claude Code’s session id by default). muxr creates all three together and carries a rename into each.

One rename across three surfaces

In order: tmux rename-session, the campaign directory within its repo (best effort, never across repos), then the runtime’s own rename command.
The runtime has no API for this; the slash command is typed into the live pane as literal text, with Enter sent separately so the agent’s TUI does not read it as a paste.

The core is a resume engine. The system prompt is a pointer: the repo’s harness rules, the campaign’s purpose, and the paths of campaign.md and log.md with an instruction to re-read them, so durable state stays on disk and survives compaction. save snapshots each session’s name, directory, runtime and conversation id; restore relaunches fresh from the pointer; upgrade relaunches each agent on a newly installed binary with --resume.

Recycle as a sentinel handshake

muxr types a flush prompt into the tool pane, naming a sentinel path.
The agent writes its state to log.md, then the sentinel. muxr waits on that file and nothing inferred; no sentinel means abort, session untouched.
muxr sends /exit, waits for the pane to return to its shell, and recreates the session fresh from the pointer.
A clean exit with no sentinel never reopens.

Session files are typed records. A missing campaign.md or log.md degrades, since an archived campaign can still be running; a present file that will not parse is an error named at that file, and recycle, upgrade and restore each refuse that session.

What varies by runtime sits outside the core. A runtime adapter is a TOML block: launch, resume and fork arguments, the slash commands for rename, model and exit, and where the conversation id lives; Claude Code and pi ship embedded. The resolver and make-durable extensions are subprocesses, JSON in and JSON out, fail closed.

Config discovery reads a muxr.toml only from the harness repositories the operator lists, because a fragment decides what runs at launch.

Created Mar 2026 · Archived Jul 2026

Retrospective →