questmaster

questmaster

questmaster is a tmux-based orchestration CLI and Bubble Tea TUI for running a small adventuring party of AI coding agents. It starts sessions, promotes a session to master, spawns workers, relays messages, and tracks agent activity from a terminal sidebar.

Prerequisites

• macOS or Linux.
• A Go 1.25.x-capable toolchain. The module declares go 1.25.7; older Go versions may only work when toolchain auto-download is enabled.
• tmux on PATH (brew install tmux, apt install tmux, or your distro package manager).
• Install and authenticate at least one agent CLI: claude, codex, or pi. A plain questmaster start uses claude by default, so install claude first or configure/start with another primary.
• For non-standard install paths, set CLAUDE_BIN, CODEX_BIN, or PI_BIN; otherwise questmaster checks PATH, then ~/.local/bin/claude, /opt/homebrew/bin/codex, or /opt/homebrew/bin/pi.

Install

go install github.com/alexivison/questmaster@latest
questmaster version

go install creates the primary questmaster binary only. If you want the optional short alias, create it yourself after installation:

mkdir -p ~/.local/bin
ln -sf "$(go env GOPATH)/bin/questmaster" ~/.local/bin/qm
qm version

From a source checkout:

go build -buildvcs=false -o questmaster .
./questmaster version

Quick start

questmaster start "fix-login-flow"
questmaster start --master --primary codex "release-triage"
questmaster spawn --prompt "Investigate the failing smoke test" "smoke-test-worker"
questmaster relay party-worker123 "Please include file:line evidence."
questmaster report "done: fixed parser edge case | PR: https://github.com/example/repo/pull/1"

Inspect state:

questmaster list
questmaster status party-1234567890
questmaster workers party-master123
questmaster read party-worker123

Install or inspect generated agent hooks:

questmaster hooks status
questmaster hooks install --dry-run
questmaster hooks install

TUI

Running questmaster with no subcommand launches the Bubble Tea tracker TUI. The TUI reads session manifests and hook activity from the questmaster state root, displays active/stale sessions, and provides keyboard-driven status tracking for the current tmux workspace.

Common entry points:

questmaster            # launch tracker TUI
questmaster sessions   # print session summary
questmaster picker     # open interactive session picker

Configuration

Configuration is read from XDG config under questmaster/config.toml:

• $XDG_CONFIG_HOME/questmaster/config.toml, or
• ~/.config/questmaster/config.toml when XDG_CONFIG_HOME is unset.

Minimal example:

[agents.claude]
cli = "claude"

[agents.codex]
cli = "codex"

[agents.pi]
cli = "pi"

[roles.primary]
agent = "claude"

State defaults to ~/.questmaster-state. Override it with QUESTMASTER_STATE_ROOT; legacy PARTY_STATE_ROOT is still read as a compatibility alias:

export QUESTMASTER_STATE_ROOT=/path/to/state

PARTY_SESSION and party-* session IDs remain part of the product vocabulary.

Legacy users upgrading from party-cli can follow MIGRATING.md.

Development

Run the standard checks:

go mod tidy
go build -buildvcs=false ./...
go test ./...
go vet ./...