How Rusuban works
Rusuban is a server on your machine. It reads your GitHub repos, starts Claude Code where something needs a decision, merges what passes its locks, and keeps for you what your rules keep.
The loop
- Reads. Every 90 seconds by default, the server reads each repo's issues, PRs, reviews, threads and CI runs through
gh, and the rules on its default branch. - Judges. When an item needs a judgment, a judge run of Claude Code reads it against the repo's rules. The judgment says what kind of item it is, whose move it is, when to look again and, for a PR, whether it may merge without a person.
- Acts. A coordinator run carries out judgments and your answers. It posts a message, closes a duplicate, or gives longer work to a worker. A worker builds, tests and fixes in a worktree of Rusuban's own clone, then opens or updates a PR.
- Merges. The server, never an agent, merges a PR when its eight gates pass, on the exact head it checked. At most one merge per read.
- Asks you. What the rules keep for you, or do not cover, becomes a card in your inbox.
The runs
Every run is a headless Claude Code session, claude -p, on the model you chose and under your host profile.
| Run | Starts when | Does |
|---|---|---|
| Judge | An issue or a PR needs a judgment: it is new, it changed, or its time to look again came | Judges items against the rules, and writes cards for what the rules keep |
| Coordinator | An answer, a request or a worker's report arrives | Posts messages, closes, labels, and starts workers |
| Worker | The coordinator gives it a mission | Builds, tests and fixes in its own worktree, then reports back |
| Task | At its times, or on a click | Carries out a task you wrote as text |
Each run gets one prompt, built when it starts: the product prompt of its kind, the safety frame, your rules as you wrote them, the context of the project, and its mission.
Cards
A card says what the agents did and asks one question. Each option says what happens next. One is marked recommended, and an option may carry a merge order that the server carries out on the head the card was written on.
Your rules say which decisions are urgent. An urgent card pings you at once on your channels; the others wait for the digest. When several cards ask the same thing, an agent proposes the rule that would answer them, as a PR you merge.
What holds the agents
- GitHub content is data. An issue, a PR or a comment never instructs an agent, even one that reads like a rule.
- Agents never merge. Merge commands and APIs are denied to them. The server merges after its gates.
- Rules come from the default branch only. A PR cannot change the rules it is judged by, and a PR that touches
.rusuban/never merges alone. - Your settings stay yours. A repo's
.claude/settings never load into a run, and what agents may run on your machine is your host profile.
The security model covers the rest, and says what stays at risk.
The dashboard
- A graph and a kanban per project, with each PR's gates and the first one that stops it.
- The inbox, with every project's cards.
- The journal of every action, merge and settings change, with where it came from.
- Every Claude conversation about an item, linked to it, read and answered from there.