donmai

README

donmai

Status: alpha. APIs and command flags are stabilising. See CHANGELOG.md for the change log and RELEASING.md for the release process.

donmai is the open-source CLI and terminal dashboard for Rensei agent fleets. It is the single binary for every OSS operator task: running the three-process stack locally, managing agents and sessions, querying issue trackers, and inspecting fleet health.

Binary: donmai Module: github.com/RenseiAI/donmai

---

Contents

• Install
• Quick start
• Credentials in standalone mode (no daemon, no platform)
• Three-process model
• Command catalog
  • donmai status
  • donmai agent
  • donmai session
  • donmai daemon
  • donmai governor
  • donmai worker and donmai fleet
  • donmai orchestrator
  • donmai logs
  • donmai linear
  • donmai github
  • donmai code
  • donmai arch
  • donmai admin
• Migration from the legacy TypeScript CLI
• Development
• Architecture
• Contribution and license

---

Install

Homebrew (macOS / Linux, recommended)

brew install RenseiAI/homebrew-tap/donmai

go install (requires Go 1.25+)

go install github.com/RenseiAI/donmai/cmd/donmai@latest

GitHub release download

Pre-built binaries for macOS (arm64, amd64) and Linux (arm64, amd64) are attached to every release on the releases page.

Example for macOS arm64 (replace 0.9.4 with the version you want):

curl -fsSL https://github.com/RenseiAI/donmai/releases/download/v0.9.4/donmai_0.9.4_darwin_arm64.tar.gz \
  | tar -xz -C /usr/local/bin donmai

Build from source

git clone https://github.com/RenseiAI/donmai
cd donmai
make build        # produces bin/donmai

---

Quick start

# 1. Authenticate with Linear (set your API key)
export LINEAR_API_KEY=lin_api_...

# 2. Start the local daemon (persists across reboots via launchd / systemd)
donmai daemon install
donmai daemon status

# 3. Pick up Linear backlog issues and dispatch agents
donmai orchestrator --project MyProject

# 4. Watch fleet activity
donmai status
donmai agent list

# 5. Tail logs from the log analyzer
donmai logs analyze --input ~/.rensei/logs/agent.log

---

Credentials in standalone mode (no daemon, no platform)

When you run donmai outside of rensei-tui (standalone OSS mode), agents inherit credentials from the donmai process. There are two sources, in this order:

1. Existing environment variables in the donmai process
2. .env.local at the root of the working directory

The first source that defines a variable wins. .env.local is read once at donmai startup and never copied into worktrees.

Some variables (the daemon's own auth tokens) are blocked from forwarding regardless of source; see internal/credentials/blocklist.go.

If you want secrets sourced from 1Password instead of a flat file, see the optional op CLI integration (run donmai creds setup for the walkthrough).

---

Three-process model

donmai manages three cooperating processes on your local machine. Each has a distinct role; together they form the complete OSS execution pipeline.

┌──────────────────────────────────────────────────────────────────┐
│                        your machine                              │
│                                                                  │
│  ┌─────────────────┐    ┌─────────────────┐   ┌──────────────┐  │
│  │   orchestrator  │───▶│    governor     │──▶│   worker(s)  │  │
│  │  (donmai orche- │    │  (donmai govr.) │   │ (donmai wkr) │  │
│  │   ator)         │    │                 │   │              │  │
│  └─────────────────┘    └─────────────────┘   └──────────────┘  │
│           │                      │                    │          │
│     Linear API             Redis queue         coordinator HTTP  │
└──────────────────────────────────────────────────────────────────┘

Orchestrator (donmai orchestrator)

Queries the Linear backlog, selects issues that satisfy the configured project/work-type filters, and dispatches agent tasks into the Redis work queue. It does not run agents itself — it schedules them. OSS users run the orchestrator on demand or via a cron job. SaaS users replace it with the platform's webhook- driven control plane.

Governor (donmai governor)

Long-running scan loop. Watches the Redis queue for pending work, enforces concurrency limits, and starts workers to consume each item. The governor is the process that keeps workers running; it is the OSS equivalent of the SaaS coordinator service.

Worker (donmai worker)

An agent process. Registers with the coordinator over HTTP, polls for work, executes the assigned session (calling the LLM runtime: Claude, Codex, etc.), and reports results back. Multiple workers can run in parallel; the governor controls the ceiling.

Daemon (donmai daemon)

The local daemon (rensei-daemon subprocess) is the persistent service that ties the three processes together. It installs as a system service (launchd on macOS, systemd on Linux), survives reboots, manages the workarea pool, and handles auto-updates with drain semantics. For the full daemon operations manual see 011-local-daemon-fleet.md.

---

Command catalog

All commands output JSON when --json is passed. Destructive commands require interactive confirmation unless --yes is provided.

donmai status

Print a fleet-wide status snapshot.

donmai status
donmai status --json

donmai agent

Inspect and control individual agent sessions.

donmai agent list [--all] [--json] [--sandbox <id>]
donmai agent status <session-id>
donmai agent stop <session-id>
donmai agent chat <session-id>          # forward a prompt to a running agent
donmai agent reconnect <session-id>     # re-attach to a detached session

donmai session

Low-level session management (lifecycle, streaming output).

donmai session list [--status <status>] [--limit <n>]
donmai session inspect <session-id>
donmai session stream <session-id>      # tail activity stream
donmai session restore-workarea <session-id> --to <dir>

donmai daemon

Start and manage the local daemon. The daemon installs as a launchd agent (macOS) or systemd user unit (Linux) and manages the workarea pool, auto- updates, and session lifecycle.

donmai daemon install [--user | --system]   # write and load the system service
donmai daemon uninstall                     # remove the system service
donmai daemon status                        # running / stopped / draining
donmai daemon start
donmai daemon stop
donmai daemon restart
donmai daemon pause                         # stop accepting new work
donmai daemon resume
donmai daemon drain                         # wait for in-flight sessions, then stop
donmai daemon update                        # force-pull latest release
donmai daemon doctor                        # health check: config, credentials, disk
donmai daemon logs [--follow]              # tail daemon log (NDJSON / pretty)
donmai daemon stats [--pool]               # capacity, sessions, pool state
donmai daemon setup                        # first-run interactive wizard
donmai daemon set <key> <value>            # mutate a single config key
donmai daemon evict --repo <repo> [--older-than <duration>]

Supported capacity keys:

donmai daemon set capacity.maxConcurrentSessions <sessions>
donmai daemon set capacity.poolMaxDiskGb <gb>

Environment: RENSEI_DAEMON_TOKEN (optional — donmai daemon install provisions this automatically when ~/.config/rensei/config.json contains a platform key).

donmai governor

Start, stop, and query the governor scan loop.

donmai governor start [--max <n>] [--interval <seconds>]
donmai governor stop
donmai governor status

donmai worker and donmai fleet

Legacy local process-manager commands for standalone OSS debugging. donmai daemon is the primary host lifecycle surface for normal operation, while these commands remain available in the donmai binary for users who need the older foreground worker host or PID-file fleet flow.

donmai worker start [--base-url <url>] [--provisioning-token <token>]
donmai fleet start --count <n>
donmai fleet status
donmai fleet stop
donmai fleet scale --count <n>

donmai orchestrator

Local orchestrator for OSS users. Queries the Linear backlog and dispatches agent tasks.

donmai orchestrator --project <name>            # dispatch from a Linear project
donmai orchestrator --single <issue-id>         # process one specific issue
donmai orchestrator --project <name> --dry-run  # preview without dispatching
donmai orchestrator --project <name> --max 5    # cap concurrent dispatches
donmai orchestrator --project <name> --repo github.com/org/repo
donmai orchestrator --project <name> --templates .donmai/templates

Environment: LINEAR_API_KEY required.

donmai logs

Agent log analysis — detect failure patterns and optionally file Linear issues.

donmai logs analyze --input /path/to/agent.log
cat agent.log | donmai logs analyze
donmai logs analyze --input agent.log --dry-run
donmai logs analyze --input agent.log --json
donmai logs analyze --input agent.log --team Engineering --project Agent
donmai logs analyze --input agent.log --config ~/.config/af/log-signatures.yaml

The built-in signature catalog covers: tool misuse, sandbox permission errors, approval-required blocks, rate-limit hits, and environment failures. Override or extend via a YAML catalog at ~/.config/af/log-signatures.yaml.

Environment: LINEAR_API_KEY required for issue creation (omit with --dry-run).

donmai linear

Linear issue-tracker operations (mirrors the legacy pnpm af-linear scripts). All subcommands output JSON.

donmai linear get-issue <id>
donmai linear create-issue --title "..." --team "..."
donmai linear update-issue <id> [--state "..."]
donmai linear list-issues [--project "..."] [--status "..."]
donmai linear create-comment <issue-id> --body "..."
donmai linear list-comments <issue-id>
donmai linear add-relation <issue-id> <related-id> --type <related|blocks|duplicate>
donmai linear list-relations <issue-id>
donmai linear remove-relation <relation-id>
donmai linear list-sub-issues <parent-id>
donmai linear list-sub-issue-statuses <parent-id>
donmai linear update-sub-issue <id> [--state "..."] [--comment "..."]
donmai linear check-blocked <issue-id>
donmai linear list-backlog-issues --project "..."
donmai linear list-unblocked-backlog --project "..."
donmai linear create-blocker <source-issue-id> --title "..."

Authentication: set LINEAR_API_KEY (or LINEAR_ACCESS_TOKEN).

donmai github

GitHub Issues operations. Mirrors the donmai linear surface adapted to GitHub Issues vocabulary. All subcommands output JSON.

donmai github get-issue     --repo owner/repo --number 42
donmai github create-issue  --repo owner/repo --title "Bug: ..." [--body "..."] [--labels "bug,enhancement"] [--assignees "alice"]
donmai github update-issue  --repo owner/repo --number 42 [--title "..."] [--state open|closed]
donmai github list-issues   --repo owner/repo [--state open|closed|all] [--labels "..."] [--assignee "alice"] [--limit 50]
donmai github list-comments --repo owner/repo --number 42
donmai github create-comment --repo owner/repo --number 42 --body "..." [--body-file /path]
donmai github add-labels    --repo owner/repo --number 42 --labels "bug,priority:high"
donmai github set-assignees --repo owner/repo --number 42 --assignees "alice,bob"
donmai github close-issue   --repo owner/repo --number 42 [--comment "Resolved in v2.0"]
donmai github reopen-issue  --repo owner/repo --number 42 [--comment "Reopening for follow-up"]
donmai github list-labels   --repo owner/repo
donmai github get-repo      --repo owner/repo

Owner/repo shorthand: --repo owner/repo sets both owner and repo. --owner and --repo also read GITHUB_OWNER / GITHUB_REPO env vars.

Authentication: set GITHUB_TOKEN (personal access token, fine-grained token, or GitHub App installation token). When running under a platform login session, GitHub calls are proxied through the platform's connected GitHub App installation credential instead.

donmai code

Code intelligence commands (repo map, symbol search, BM25 + vector hybrid search).

donmai code search <query>
donmai code map [--depth <n>]
donmai code symbols <file>

donmai arch

Architecture reference commands. Browse, show, and synthesize the donmai-architecture corpus.

donmai arch list
donmai arch show <doc-id>                    # e.g. donmai arch show 001
donmai arch browse                           # interactive TUI browser
donmai arch synthesize --topic <topic>
donmai arch assess --topic <topic>           # gap/consistency assessment

donmai admin

Operational admin commands for cleanup, queue inspection, and merge-queue management. All subcommands output JSON. Destructive operations require interactive confirmation unless --yes is passed.

Environment: REDIS_URL must be set for queue and merge-queue subcommands.

---

donmai admin cleanup

Prune orphaned git worktrees and stale local branches. Mirrors the TypeScript af-cleanup + af-cleanup-sub-issues scripts.

donmai admin cleanup [flags]

Flags:
  --dry-run          Show what would be cleaned without removing
  --force            Force removal (includes branches with gone remotes)
  --path <dir>       Custom worktrees directory (default: ../<repoName>.wt)
  --skip-worktrees   Skip worktree cleanup
  --skip-branches    Skip branch cleanup
  --yes              Skip confirmation prompt

Example output:

{
  "dryRun": false,
  "worktrees": {
    "scanned": 12,
    "orphaned": 3,
    "cleaned": 3,
    "skipped": 0,
    "errors": []
  },
  "branches": {
    "scanned": 5,
    "deleted": 5,
    "errors": []
  }
}

---

donmai admin queue

Inspect and mutate the Redis work queue.

donmai admin queue list
donmai admin queue peek
donmai admin queue requeue <session-id> [--yes]
donmai admin queue drop <session-id> [--yes]

• list — returns all work items, sessions, and registered workers as JSON
• peek — shows the next item in the queue without removing it
• requeue — resets a session from running/claimed back to pending (destructive)
• drop — permanently removes a session and its queue/claim entries (destructive)

Example: donmai admin queue list:

{
  "items": [
    {
      "sessionId": "sess-abc123",
      "issueIdentifier": "REN-42",
      "workType": "development",
      "priority": 2,
      "queuedAt": 1714000000000
    }
  ],
  "sessions": [...],
  "workers": [...]
}

---

donmai admin merge-queue

Inspect and mutate the Redis merge queue.

donmai admin merge-queue list [--repo <repoId>]
donmai admin merge-queue dequeue <pr-number> [--repo <repoId>] [--yes]
donmai admin merge-queue force-merge <pr-number> [--repo <repoId>] [--yes]

• list — returns all queued, failed, and blocked PRs for the repo
• dequeue — permanently removes a PR from the merge queue (destructive)
• force-merge — moves a failed/blocked PR back to the head of the queue (destructive)

The --repo flag defaults to "default".

Example: donmai admin merge-queue list --repo my-org/my-repo:

{
  "repoId": "my-org/my-repo",
  "depth": 2,
  "entries": [
    {
      "repoId": "my-org/my-repo",
      "prNumber": 42,
      "sourceBranch": "feature/foo",
      "priority": 1,
      "enqueuedAt": 1714000000000,
      "status": "queued"
    },
    {
      "repoId": "my-org/my-repo",
      "prNumber": 7,
      "sourceBranch": "feature/bar",
      "status": "failed",
      "failureReason": "merge conflict"
    }
  ]
}

---

Migration from the legacy TypeScript CLI

If you are moving from the previous TypeScript-based pnpm af-* scripts, see migration-from-legacy-cli.md (REN-1365 in flight).

---

Development

make build      # Build donmai binary  →  bin/donmai
make test       # go test -race ./...
make lint       # golangci-lint run
make fmt        # gofumpt -w .
make vuln       # govulncheck ./...
make coverage   # Test with coverage report
make run-mock        # Run TUI dashboard with mock data
make run-status-mock # Run status with mock data

---

Architecture

The public library surface (afclient, afcli, worker) is designed to be imported by downstream consumers. Embedders use afcli.RegisterCommands and extend the generic OSS command set with their own subcommands. The standalone donmai binary opts into legacy worker/fleet process-manager commands; embedders that want the daemon-only lifecycle surface can leave those commands disabled.

See AGENTS.md for the full package layout and contributor guide. The authoritative architecture corpus lives in donmai-architecture — particularly:

• 001-layered-execution-model.md — layered execution model and OSS contracts
• 011-local-daemon-fleet.md — local daemon operations manual
• 013-orchestrator-and-governor.md — orchestrator, governor, worker, dispatch loop
• 014-tui-operator-surfaces.md — TUI display primitives and dual-surface discipline

---

Contribution and license

Contributions welcome. Please open an issue or PR; follow the conventions in AGENTS.md. The project uses the MIT license — see LICENSE.

See CHANGELOG.md and RELEASING.md for the change history and release process.