Install Rusuban

Rusuban is an npm package. It runs on your own machine, Windows, macOS or Linux, as a service with a dashboard in your browser.

What you need

  • Node.js 22 or later.
  • The GitHub CLI, gh, logged in. The agents act on GitHub through this login, so their comments and PRs appear under your account.
  • Claude Code, claude, logged in. The agents run on your Claude plan, within its usage limits.

Rusuban itself is free and open source, under the MIT license.

Install and set up

npm install -g rusuban
rusuban init

rusuban init asks three things:

  1. The Claude model every run uses. Runs never fall back to Claude Code's default.
  2. What agents may run on this machine: only what you allow (allowlist), or anything a deny rule does not stop (bypass). The security model explains both.
  3. Whether to arm automatic merges. Merges stay paused unless you arm them, here or later with the switch in the dashboard's header.

It then adds your first repo, installs the service and opens the dashboard.

On Linux without a desktop session, run loginctl enable-linger once. Otherwise systemd stops the service when you log out.

Write your rules

Until a repo has rules, Rusuban only watches it: its items show in the dashboard, no agent judges them, and nothing merges.

Rules are Markdown files in .rusuban/rules/, on the repo's default branch. Start from one of the examples, then read Writing rules.

Add repos

rusuban project add owner/repo
rusuban project list

With --to <project>, the repo joins an existing project. A project can hold several repos, and its runs see the rules of each.

Answer from your phone

rusuban remote enable

The dashboard is then served on your tailnet through Tailscale Serve, never through Tailscale Funnel or a public address. It answers only you: the identity Tailscale gives each request must match the owner's login in your config.

Get pinged

rusuban channel add ntfy https://ntfy.sh/<your-topic>
rusuban channel test <id>

A channel sends cards to ntfy, Slack, Discord, Teams or e-mail. An urgent card goes at once. The others go together at the channel's digest time (--digest HH:MM), never in its quiet hours (--quiet HH:MM-HH:MM).

Try it without risk

  • Keep merges paused. Agents act as your rules say, and nothing merges until you arm the switch.
  • Run rusuban start --dry. The dashboard reads and shows, and starts no agent.

Where things live

Rusuban keeps its state in ~/.rusuban/, never in your repos. RUSUBAN_HOME moves it. Agents work in Rusuban's own clones and worktrees, never in your checkout.

Next