https://github.com/renseiai/donmai

Last synced: 29 days ago
JSON representation

Host: GitHub
URL: https://github.com/renseiai/donmai
Owner: RenseiAI
License: mit
Created: 2026-03-21T04:45:32.000Z (4 months ago)
Default Branch: main
Last Pushed: 2026-06-01T16:50:07.000Z (about 1 month ago)
Last Synced: 2026-06-01T18:22:34.141Z (about 1 month ago)
Language: Go
Size: 1.99 MB
Stars: 3
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md

Awesome Lists containing this project

README

# donmai

> **Status: alpha.** APIs and command flags are stabilising. See [CHANGELOG.md](./CHANGELOG.md) for the change log and [RELEASING.md](./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](#install)
- [Quick start](#quick-start)
- [Credentials in standalone mode (no daemon, no platform)](#credentials-in-standalone-mode-no-daemon-no-platform)
- [Three-process model](#three-process-model)
- [Command catalog](#command-catalog)
- [donmai status](#donmai-status)
- [donmai agent](#donmai-agent)
- [donmai session](#donmai-session)
- [donmai daemon](#donmai-daemon)
- [donmai governor](#donmai-governor)
- [donmai worker and donmai fleet](#donmai-worker-and-donmai-fleet)
- [donmai orchestrator](#donmai-orchestrator)
- [donmai logs](#donmai-logs)
- [donmai linear](#donmai-linear)
- [donmai github](#donmai-github)
- [donmai code](#donmai-code)
- [donmai arch](#donmai-arch)
- [donmai admin](#donmai-admin)
- [Migration from the legacy TypeScript CLI](#migration-from-the-legacy-typescript-cli)
- [Development](#development)
- [Architecture](#architecture)
- [Contribution and license](#contribution-and-license)

---

## Install

### Homebrew (macOS / Linux, recommended)

```bash
brew install RenseiAI/homebrew-tap/donmai
```

### go install (requires Go 1.25+)

```bash
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](https://github.com/RenseiAI/donmai/releases).

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

```bash
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

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

---

## Quick start

```bash
# 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](https://github.com/RenseiAI/donmai-architecture/blob/main/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.

```bash
donmai status
donmai status --json
```

### `donmai agent`

Inspect and control individual agent sessions.

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

### `donmai session`

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

```bash
donmai session list [--status ] [--limit ]
donmai session inspect
donmai session stream # tail activity stream
donmai session restore-workarea --to
```

### `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.

```bash
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 # mutate a single config key
donmai daemon evict --repo [--older-than ]
```

Supported capacity keys:

```bash
donmai daemon set capacity.maxConcurrentSessions
donmai daemon set capacity.poolMaxDiskGb
```

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.

```bash
donmai governor start [--max ] [--interval ]
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.

```bash
donmai worker start [--base-url ] [--provisioning-token ]
donmai fleet start --count
donmai fleet status
donmai fleet stop
donmai fleet scale --count
```

### `donmai orchestrator`

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

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

**Environment**: `LINEAR_API_KEY` required.

### `donmai logs`

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

```bash
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.

```bash
donmai linear get-issue
donmai linear create-issue --title "..." --team "..."
donmai linear update-issue [--state "..."]
donmai linear list-issues [--project "..."] [--status "..."]
donmai linear create-comment --body "..."
donmai linear list-comments
donmai linear add-relation --type
donmai linear list-relations
donmai linear remove-relation
donmai linear list-sub-issues
donmai linear list-sub-issue-statuses
donmai linear update-sub-issue [--state "..."] [--comment "..."]
donmai linear check-blocked
donmai linear list-backlog-issues --project "..."
donmai linear list-unblocked-backlog --project "..."
donmai linear create-blocker --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.

```bash
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).

```bash
donmai code search
donmai code map [--depth ]
donmai code symbols
```

### `donmai arch`

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

```bash
donmai arch list
donmai arch show # e.g. donmai arch show 001
donmai arch browse # interactive TUI browser
donmai arch synthesize --topic
donmai arch assess --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.

```bash
donmai admin cleanup [flags]

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

Example output:
```json
{
"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.

```bash
donmai admin queue list
donmai admin queue peek
donmai admin queue requeue [--yes]
donmai admin queue drop [--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`:
```json
{
"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.

```bash
donmai admin merge-queue list [--repo ]
donmai admin merge-queue dequeue [--repo ] [--yes]
donmai admin merge-queue force-merge [--repo ] [--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`:
```json
{
"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](https://github.com/RenseiAI/donmai-libraries/blob/main/docs/migration-from-legacy-cli.md)
(REN-1365 in flight).

---

## Development

```bash
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](https://github.com/RenseiAI/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](./CHANGELOG.md) and [RELEASING.md](./RELEASING.md)
for the change history and release process.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/renseiai/donmai

Awesome Lists containing this project

README