setup

name	setup
description	Use when the user runs /komandant:setup or asks to install, configure, or bootstrap the komandant daemon after installing the plugin. Interactive postinstall — preflight checks, local go build of the binary, workflow install into ~/.claude/workflows, conversational config.json scaffold, optional launchd service, and the run commands.

komandant:setup

Interactive postinstall for the komandant daemon. Work through the steps in order and stop at the first failure — report what broke and how to fix it; never continue on a broken precondition, never substitute a fallback.

1. Preflight

Run every check; all must pass:

gh auth status        # authenticated GitHub CLI
tmux -V               # tmux installed
claude --version      # must be >= 2.1.154 (dynamic workflows)
go version            # must be >= 1.22

Compare versions numerically, not as strings. If claude is too old, the worker workflow cannot run — stop and tell the user to update.

Remind the user: dynamic workflows must be enabled for their Claude account. komandant workers run the komandant-implement workflow; without the feature enabled, every worker fails after the daemon has already claimed the issue.

2. Locate the source and build the binary

Find the komandant checkout, in order:

1. The marketplace clone: ~/.claude/plugins/marketplaces/komandant/
2. A manual checkout — ask the user for the path.

Verify it is the right repo (main.go and workflows/komandant-implement.js exist). Confirm the install destination with the user — default ~/.local/bin/komandant, and it must be on their PATH — then build:

cd <source> && CGO_ENABLED=0 go build -o ~/.local/bin/komandant .

Verify the build actually produced a working binary:

~/.local/bin/komandant run --help

3. Install the worker workflow

mkdir -p ~/.claude/workflows
cp <source>/workflows/komandant-implement.js ~/.claude/workflows/

Tell the user explicitly: plugins cannot ship workflows (the plugin root path changes across versions), so the stable copy lives in ~/.claude/workflows/ and must be re-copied after every plugin update. The daemon fails at startup when this file is missing.

4. Scaffold config.json

Build the config conversationally — ask for:

• the managed repos: local path + tmux session name each, plus an optional per-repo trigger-label override,
• whether to change the defaults for poll interval, labels, and the babysit knobs (babysit_max_rounds, babysit_cooldown_minutes, audit_docs),
• per-role effort/model overrides (empty string = omit the flag, claude's own default applies).

Validate before writing: every repo path must exist ([ -d <path> ]), and no session may be named komandant — that session is reserved for the controller.

Suggest ~/.komandant/config.json (mkdir -p ~/.komandant) and write it in this schema (matches config.example.json in the source repo):

{
  "poll_interval": 60,
  "trigger_label": "komandant",
  "in_progress_label": "komandant-in-progress",
  "in_review_label": "komandant-in-review",
  "finished_label": "komandant-finished",
  "feedback_label": "komandant-feedback-required",
  "log_file": "~/.komandant/komandant.log",
  "babysit_max_rounds": 3,
  "babysit_cooldown_minutes": 45,
  "audit_docs": false,
  "controller_effort": "medium",
  "controller_model": "",
  "worker_effort": "",
  "worker_model": "",
  "babysit_effort": "",
  "babysit_model": "",
  "repos": [
    { "path": "/path/to/repo", "session": "repo" },
    { "path": "/path/to/other", "session": "other", "label": "ai-fix" }
  ]
}

5. launchd service (macOS, optional)

Offer to install a LaunchAgent so the daemon starts at login. If accepted, write ~/Library/LaunchAgents/com.komandant.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.komandant</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/USER/.local/bin/komandant</string>
    <string>run</string>
    <string>--config</string>
    <string>/Users/USER/.komandant/config.json</string>
  </array>
  <key>WorkingDirectory</key><string>/path/to/komandant-source</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key><string>GH_DIR:TMUX_DIR:CLAUDE_DIR:/usr/bin:/bin:/usr/sbin:/sbin</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/Users/USER/.komandant/launchd.log</string>
  <key>StandardErrorPath</key><string>/Users/USER/.komandant/launchd.log</string>
</dict>
</plist>

Substitute every placeholder with real values before writing the file:

• the home directory and binary path (launchd does not expand ~),
• WorkingDirectory: the komandant source checkout path from step 2,
• PATH: launchd's default is /usr/bin:/bin:/usr/sbin:/sbin, which has none of the daemon's dependencies — resolve their dirs now and prepend them (deduplicated):

dirname "$(which gh)"
dirname "$(which tmux)"
dirname "$(which claude)"

Without these two keys the daemon cannot exec gh/tmux/git and KeepAlive turns every failure into a crash loop.

This PATH is also inherited by the tmux server if the daemon is what starts it (no interactive session yet) — and every worker claude spawned in that server needs the repos' toolchains (node, go, python, …) on PATH to run tests. Prepend the user's full interactive toolchain dirs too (compare with echo "$PATH" from their shell), or make sure a tmux server is already running from an interactive login before the service starts. Then load it:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.komandant.plist

6. Per-repo environment check

Recommend running /env-check (from the suso-plugins marketplace) inside each managed repo. Worktree readiness — a WorktreeCreate hook, provisioning, teardown — is a precondition komandant does not enforce; workers run in worktrees and an unprovisioned repo fails late and confusingly.

7. Run it

Print the commands, in escalation order:

komandant run --config ~/.komandant/config.json --dry-run   # print actions, change nothing
komandant run --config ~/.komandant/config.json --once      # single real scan
komandant run --config ~/.komandant/config.json             # poll loop (or the launchd service)

Suggest starting with --once --dry-run against the real config to prove both scans work before letting the daemon loose.