komrad

How it works

The server, the panel, tmux, and the one API everything goes through.

Edit on GitHub

Komrad has two programs, a server and a panel. The server runs in the background. It owns the database and the API, and it watches every agent. The panel is the terminal UI you work in, and it doesn’t keep state of its own. The server, together with its database, its tmux server and the agents running there, makes up an engine.

The server and the panel#

Your terminal attaches to komrad's tmux server, which holds the panel and every agent. The panel and each agent talk to komrad serve, which owns Postgres.

Each agent is a real terminal running Claude or Codex. Komrad runs the agents in a tmux server of its own, so they never mix with your own tmux windows. Opening the panel attaches your terminal to komrad’s session, and closing the panel detaches that terminal without stopping anything else.

The panel, a script calling komrad rpc, and an agent calling an MCP tool all go through the same API, so they all get the same rules and the same checks. Komrad builds its CLI commands, its MCP tools and the API reference from that one API definition.

State#

Komrad keeps all of its state in Postgres, including every workflow, task, agent, piece of mail and review. State that lives somewhere else, like a pull request’s status or whether an agent’s CLI is idle, reaches Postgres through sync loops. Each loop checks an outside system on a timer and writes what it finds to the database.

The server pushes each change to the panel once it commits. A database trigger announces the write through LISTEN/NOTIFY, and the server streams the new rows to the panel over a ConnectRPC stream.

A key press reaches the panel's Update, which returns a Cmd that calls the API over Connect RPC. The API handler passes it to the business logic, and the store commits the rows to Postgres, as the sync loops do too. On commit a trigger calls pg_notify with the table and key. The listener collects the changed IDs, and the reconciler streams the new rows over the Watch stream to Update, which changes the Model that View draws.

When a write commits, its trigger sends the table and the row’s ID to a listener in the server. A reconciler reads those rows back, works out what each client hasn’t seen yet, including rows that were deleted, and streams the difference to the panel.

The panel never updates its own state from an API response. When it makes a call that changes something, it waits for the change to come back through the stream after the database commits it, and redraws from there.

State reaches the screen by that one path, which fits Bubble Tea’s Elm architecture and keeps several panels on one engine in step. It also makes rendering bugs easier to track down. The server stays small as a result, and it uses far less memory than the coding CLIs it runs.