komrad

Philosophy

An overview of the design principles behind komrad.

Edit on GitHub

Welcome, komrad!#

Komrad is an open-source, terminal-based agent orchestrator.

I’m using it as my daily driver these days, and most of the design decisions come from my desire for an agent orchestration tool that I actually enjoyed using. That drives a handful of principles:

  1. For the time being, stability of existing features takes precedence over large feature builds.
  2. No data loss. You can close and open the view at any time, and finding or recovering the right agent, chat or branch should not be hard.
  3. It meets you in the terminal, and uses familiar keybindings.
  4. It runs locally, but can also be fully self-hosted.

These decisions bring some big wins and some tradeoffs, which I outline below.

Slop: Don’t be a meat proxy#

You may have seen earlier this year when the “gastown” maintainer said this:

I’ve never seen the code, and I never care to, which might give you pause. ‘Course, I’ve never looked at Beads either, and it’s 225k lines of Go code that tens of thousands of people are using every day. I just created it in October. If that makes you uncomfortable, get out now.

Komrad takes a different approach. I’m not convinced that software engineers don’t need to read the code they ship. Komrad is accordingly architected to make it easy, not hard, to drop into an editor, review diffs, and to work incrementally.

It’s probably not as efficient as these other orchestration tools. For instance, komrad syncs review comments from your forge (like Github) but won’t reply to them for you. Komrad never posts anything back to the forge on your behalf, because replying to another human being is your responsibility.

In my opinion, this is a good tradeoff. If you are building an architecture you intend to explain to others and scale over time, this is a saner way to work.

Focus on stability#

For the time being, I’m focusing on stability.

Focusing on stability instead of packing in new features keeps me, the sole maintainer, sane.

Usability problems count as bugs, though. Confusing screens, unclear errors, and so forth are still worth reporting, as are overhauls of existing workflows. Feature ideas are still welcome in Discussions, and they will be read and weighed once the stability period ends.

Why Postgres?#

Everything komrad knows is written to a Postgres database before it is acted on. Close the panel, close the terminal, log out, and nothing is lost. An archived agent can be restored and its conversation searched. How it works covers the mechanics.

Most agent orchestration tools ship a simpler persistence layer. Postgres gives komrad a powerful core with row-level security, listen-notify patterns, semantic search, and durable job execution. Postgres is heavier than a file in your home directory, no doubt. Komrad uses it anyway. Sorry! On a laptop, komrad runs the embedded Postgres, so you have nothing extra to install.

Komrad is terminal-based#

Komrad is designed for people who already work in a terminal. It is not a desktop app.

Each agent is a real terminal in a real tmux server. To take over from an agent, attach to its pane, which is just a tmux session.

As such, komrad tries to be familiar to folks used to vim-like keybindings: use g to jump to the top of the view, use / to search, and so forth. Nearly all of these keybindings are configurable.

There are other tools (listed below) that are very polished desktop apps. If you prefer that, use them instead. I’ve no plans to ship a mobile client for this tool.

Self-hosting#

Komrad typically runs on your machine. Locally, agents can have the same MCP tools and permissions you do. Remotely, you set the environment up however you want.

For instance, each person on komrad’s team runs their agents on an engine of their own in AWS. You don’t need a komrad account, and komrad doesn’t run a hosted service. Running komrad remotely explains how to set up your own.

Alternative tools#

There are lots of options out there for agent orchestration.

They all do similar things to komrad, and many are more mature products.

Some of them are easier to install, some send notifications outside the terminal, and most are regular desktop applications. If one of them fits the way you work better, use it.