CLI reference¶

The generated reference below comes from the installed Click commands. For day-to-day coordination, use these groups instead of editing files under .greatminds/ by hand:

Need	Command surface
Create, inspect, move, or annotate tasks	`greatminds task ...`
Send, read, or acknowledge inter-role messages	`greatminds inbox ...`
Acquire, prepare, inspect, or release the singleton stand	`greatminds stand ...`
Inspect transition history	`greatminds journal ...`
Inspect live agent pids, sessions, venvs, heartbeats, and input sockets	`greatminds agent status [ROLE]`
Watch chronological driven-agent turn events	`greatminds driven-log --follow`
Check stand-gate evidence	`greatminds gate-check <task-id>`
Check blocked-task readiness	`greatminds wake-check`
Check stale agents, stale tasks, and orphaned intents	`greatminds watchdog`
Launch, restart, or update a fleet	`greatminds launch`, `greatminds restart`, `greatminds update`
Inspect project docs and runtime paths	`greatminds project ...`, `greatminds task paths`

greatminds¶

File-based multi-agent coordination protocol — fleet orchestration, task pipeline, agent launcher.

Usage:

greatminds [OPTIONS] COMMAND [ARGS]...

Options:

  --version   Show the version and exit.
  -h, --help  Show this message and exit.

greatminds agent¶

per-agent process diagnostics.

Usage:

greatminds agent [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds agent status¶

report pid/alive/session/venv/heartbeat/input_sock for one or more roles (or every registered role).

Usage:

greatminds agent status [OPTIONS] [ROLES]...

Options:

  --json      emit a machine-readable JSON array (cat replacement).
  --no-pane   skip tmux pane inspection.
  -h, --help  Show this message and exit.

greatminds agent tools¶

list supported agent tools and execution modes.

Usage:

greatminds agent tools [OPTIONS]

Options:

  --json      emit a machine-readable JSON array.
  -h, --help  Show this message and exit.

greatminds check-git-permission¶

greatminds check-git-permission — gate git commit / git push by role.

Installed by greatminds setup as a pre-commit hook. Reads schema.yaml git_permissions and refuses if $GREATMINDS_ROLE is not in the allowed list for the given verb.

Usage::

greatminds check-git-permission commit
greatminds check-git-permission push

Exit codes: 0 allowed (or GREATMINDS_ROLE is in git_permissions.) 2 $GREATMINDS_ROLE unset or not allowed for this verb 3 schema lookup failed (missing section or unreadable file)

Task 0091 item 2.

Usage:

greatminds check-git-permission [OPTIONS] {commit|push}

Options:

  -h, --help  Show this message and exit.

greatminds coordd¶

coordd — optional coordination daemon. Closes the ScheduleWakeup gap.

Two responsibilities, run every seconds:

Drive notify_from_journal — replay any new journal.ndjson lines and write wake-up messages to inbox//. (If PostToolUse hooks already did this, the call is a cheap no-op since state advances monotonically.)
Scan .greatminds/inbox// for new files. For each new file, find the role's active TTY from .greatminds/.agent_registry/.json and write "check inbox and continue your tick " to that TTY. The sleeping agent wakes, reads the inbox, and continues the tick.

If the daemon is NOT running, agents still work via their own fallback polling, but queue and inbox reaction latency is higher. The daemon is additive: killing it does not mutate task state.

The daemon never moves task files, never edits queues, never decides on state. Its only side effects are: - replaying journal transitions through notify_from_journal (which writes inbox messages), - writing wake-up text to known agent TTYs.

State sources (read-only): - .greatminds/inbox//*.md — new files to react to - .greatminds/.agent_registry/.json — written by greatminds start-agent with {role, tool, pid, tty, started_at}

Usage: greatminds coordd [--project-dir

] [--interval-sec 1.0] [--verbose]

For a long-lived install, run via systemd-user with greatminds daemon install.

Usage:

greatminds coordd [OPTIONS]

Options:

  --project-dir DIRECTORY  project root containing .greatminds/ (default: cwd
                           or registry lookup via --project)
  --project TEXT           project name; resolved to project_dir via
                           ~/.config/greatminds/projects.json. Used by the
                           systemd template unit greatminds-
                           daemon@<project>.service.
  --interval-sec FLOAT     polling interval; 1.0 keeps CPU near zero on idle.
                           Don't go below 0.2.
  -v, --verbose
  -h, --help               Show this message and exit.

greatminds daemon¶

greatminds daemon — per-project coordination daemon supervision.

Wraps systemctl --user to manage instances of the greatminds-daemon@<project>.service template unit. Each greatminds project on the host gets ONE daemon instance keyed by its coord.yaml: session name (or an explicit --project NAME flag), so multiple projects on the same user can run their daemons concurrently without colliding on a global unit name.

Subcommands::

greatminds daemon install [--name NAME] [--project-dir DIR]
greatminds daemon start    [--project NAME] [--project-dir DIR]
greatminds daemon stop     [--project NAME] [--project-dir DIR]
greatminds daemon restart  [--project NAME] [--project-dir DIR]
greatminds daemon status   [--project NAME] [--project-dir DIR]
greatminds daemon list
greatminds daemon migrate  [--yes]

install is idempotent: it writes the template unit if missing and adds the {name → project_dir} entry to the per-user registry at ~/.config/greatminds/projects.json.

Usage:

greatminds daemon [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds daemon doctor¶

Check whether daemon-driven agent tools work in daemon-equivalent env.

Usage:

greatminds daemon doctor [OPTIONS]

Options:

  --project TEXT           project name (default: coord.yaml session)
  --project-dir DIRECTORY  project root (default: cwd)
  --timeout-sec FLOAT      headless Claude probe timeout  [default: 60.0]
  -h, --help               Show this message and exit.

greatminds daemon install¶

install template unit + register project

Usage:

greatminds daemon install [OPTIONS]

Options:

  --name TEXT              project name (default: coord.yaml `session`)
  --project-dir DIRECTORY  project root (default: cwd)
  -h, --help               Show this message and exit.

greatminds daemon list¶

list all registered projects + active state

Usage:

greatminds daemon list [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds daemon migrate¶

remove the singleton coordd.service unit

Usage:

greatminds daemon migrate [OPTIONS]

Options:

  --yes       confirm removal of coordd.service
  -h, --help  Show this message and exit.

greatminds daemon repair¶

Idempotently enable the project's daemon instance.

Usage:

greatminds daemon repair [OPTIONS]

Options:

  --name TEXT              project name (default: coord.yaml `session`)
  --project-dir DIRECTORY  project root (default: cwd)
  -h, --help               Show this message and exit.

greatminds daemon restart¶

restart the daemon for a project

Usage:

greatminds daemon restart [OPTIONS]

Options:

  --project TEXT           project name (default: coord.yaml session)
  --project-dir DIRECTORY  project root (default: cwd)
  -h, --help               Show this message and exit.

greatminds daemon start¶

start the daemon for a project

Usage:

greatminds daemon start [OPTIONS]

Options:

  --project TEXT           project name (default: coord.yaml session)
  --project-dir DIRECTORY  project root (default: cwd)
  -h, --help               Show this message and exit.

greatminds daemon status¶

show daemon status for a project

Usage:

greatminds daemon status [OPTIONS]

Options:

  --project TEXT           project name (default: coord.yaml session)
  --project-dir DIRECTORY  project root (default: cwd)
  -h, --help               Show this message and exit.

greatminds daemon stop¶

stop the daemon for a project

Usage:

greatminds daemon stop [OPTIONS]

Options:

  --project TEXT           project name (default: coord.yaml session)
  --project-dir DIRECTORY  project root (default: cwd)
  -h, --help               Show this message and exit.

greatminds dashboard¶

live read-only fleet status table (agents / tasks / stand). Non-scrolling; Ctrl-C to exit.

Usage:

greatminds dashboard [OPTIONS]

Options:

  --interval FLOAT      refresh interval in seconds.  [default: 2.0]
  --once                print a single frame and exit (no clear, no loop).
  --color / --no-color  ANSI color. Default: auto (on when stdout is a TTY).
  --logs / --no-logs    include latest driven-agent turn log tails.  [default:
                        no-logs]
  --log-lines INTEGER   lines to show per driven-agent log when --logs is set.
                        [default: 8]
  -h, --help            Show this message and exit.

greatminds driven-log¶

read-only driven-agent event stream. Ctrl-C to exit.

Usage:

greatminds driven-log [OPTIONS]

Options:

  --lines INTEGER         initial events to print.  [default: 200]
  --follow / --no-follow  follow new events.  [default: follow]
  --interval FLOAT        poll interval while following.  [default: 1.0]
  --color / --no-color    ANSI color. Default: auto (on when stdout is a TTY).
  -h, --help              Show this message and exit.

greatminds gate-check¶

Check stand-evidence gate for a product task.

Usage: greatminds gate-check [--project-dir

] [--canon-dir ]

may be the full id (for example TASK-slug) or just the seq.

Looks up the task across coordination queues, reads its plan block, and verifies stand-evidence per the schema: - plan.stand_required: false → output 'n/a' - plan.stand_required: true → require the latest tests block to carry lease-backed stand evidence for the task commit and an acceptable result.

Exit code: 0 pass | n/a 1 fail 2 missing 3 error (task not found, malformed)

Usage:

greatminds gate-check [OPTIONS] TASK_ID

Options:

  --project-dir DIRECTORY  project root (default: cwd)
  --canon-dir DIRECTORY    canon data dir (default: packaged greatminds.data)
  -v, --verbose            print diagnostic reasons
  -h, --help               Show this message and exit.

greatminds inbox¶

inter-role inbox messaging (wake/ask/info)

Usage:

greatminds inbox [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds inbox ack¶

Usage:

greatminds inbox ack [OPTIONS] PATH

Options:

  -h, --help  Show this message and exit.

greatminds inbox list¶

Usage:

greatminds inbox list [OPTIONS] [ROLE]

Options:

  -h, --help  Show this message and exit.

greatminds inbox send¶

Usage:

greatminds inbox send [OPTIONS] TO

Options:

  --kind TEXT  message kind (schema.inbox.allowed_kinds)  [required]
  --task TEXT  task id ref
  --body TEXT  literal | @file | - (stdin)
  -h, --help   Show this message and exit.

greatminds inbox show¶

Usage:

greatminds inbox show [OPTIONS] PATH

Options:

  -h, --help  Show this message and exit.

greatminds intent-clean¶

intent-clean — remove orphan intent files whose task has already moved.

An intent file says "I'm about to mv from to ". After the mv, the agent is supposed to delete its intent. If an agent crashes mid-tick, its intent file is left behind. This command garbage- collects them: if the task is no longer in the intent's from queue, the mv has completed (or the task was withdrawn) and the intent is stale.

Safety: only removes intents older than --min-age-sec (default 300). Recently-created intents may be legitimate ongoing claims.

Usage:

greatminds intent-clean [OPTIONS]

Options:

  --project-dir DIRECTORY  project root (default: cwd)
  --min-age-sec INTEGER    only consider intents older than this; default 300s
  --dry-run                report what would be removed; don't delete
  --quiet                  suppress summary line on no-ops
  -h, --help               Show this message and exit.

greatminds journal¶

greatminds journal — read-only view of the coordination journal.

greatminds journal tail provides a clean, read-only view with -n/--role/--task filters. It never writes.

Each journal line is a JSON object::

{"t": <iso>, "actor"|"role": <ROLE>, "task": <id>,
 "from": <q>, "to": <q>, "reason": <str>, "intent_id": <str>}

Usage:

greatminds journal [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds journal tail¶

Print the last -n journal entries (read-only), optionally filtered by --role and/or --task.

Usage:

greatminds journal tail [OPTIONS]

Options:

  -n, --num INTEGER        show the last N matching entries (default 20)
  --role TEXT              only entries by this acting role
  --task TEXT              only entries for this task (short id / full id)
  --project-dir DIRECTORY  project root containing coordination/ (default:
                           cwd)
  -h, --help               Show this message and exit.

greatminds launch¶

greatminds launch — start the fleet (tmux | vscode | cursor-ide).

Reads <project>/coordination/coord.yaml, detects the project's Python env via greatminds.core.env, and:

--target tmux creates a tmux session with one window per role. Each window pre-types the env activation command (so bare greatminds start-agent works in the shell) followed by the actual launcher line (without Enter — you review and confirm).

--target vscode writes .vscode/tasks.json + a workspace file. Each task launches the agent in a dedicated terminal panel; the task env block (for simple envs) or wrapping bash -c (for pixi/conda) ensures the unified greatminds CLI is on PATH.

--target cursor-ide same generated files as vscode (Cursor IDE reads .vscode/ verbatim); prints cursor as the open command.

Env auto-detection ladder: pixi.toml | uv.lock | poetry.lock | environment.yml | .venv/bin/activate → fallback to $VIRTUAL_ENV / $CONDA_DEFAULT_ENV from parent shell → system PATH only (e.g. pipx).

Pass --venv /path to force source <path>/bin/activate and skip detection (useful when no marker files describe the env).

Usage:

greatminds launch [OPTIONS]

Options:

  --target [tmux|vscode|cursor-ide]
                                  frontend (default: tmux)
  --config FILE                   path to coord.yaml (default:
                                  <project>/coordination/coord.yaml)
  --project-dir DIRECTORY         override config.project_dir / cwd
  --venv DIRECTORY                explicit venv to activate (skips auto-
                                  detect)
  --recreate                      (tmux target only) kill existing session and
                                  rebuild
  -h, --help                      Show this message and exit.

greatminds lint-tokens¶

Lint usage across the canon coordination files.

Scans COORDINATE.md, root *.md, templates/, plugin skills and mcp configs for <TOKEN> patterns. Compares with the token catalog in PROJECT_VARIABLES.md.

Exits non-zero if unknown tokens are found. Unused catalog tokens are warned about but do not fail.

Usage:

greatminds lint-tokens [OPTIONS]

Options:

  --canon-dir DIRECTORY  canon data dir (default: packaged greatminds.data)
  -h, --help             Show this message and exit.

greatminds migrate¶

Bring a project's coord.yaml / canon / queues up to the installed greatminds version. Idempotent; backs up coord.yaml.

Usage:

greatminds migrate [OPTIONS]

Options:

  --project-dir TEXT  project root (default: cwd).
  --no-setup          skip the canon refresh (setup) step.
  -h, --help          Show this message and exit.

greatminds migrate-stand-history¶

Archive coordination/stand_done/* under coordination/archive/stand-history/.

Usage:

greatminds migrate-stand-history [OPTIONS]

Options:

  --coord TEXT  path to coordination/ (default: resolved via env / cwd)
  --dry-run     report what would move; touch nothing
  -h, --help    Show this message and exit.

greatminds migrate-task¶

greatminds migrate-task — convert markdown task files to strict .yaml.

Input format: a markdown file with multiple YAML blocks separated by ---, optionally interleaved with free prose. * the first dict-shaped YAML block is the header (id, stream, kind, ...); * subsequent dict-shaped YAML blocks whose only top-level key is a known "_block" name are progress blocks; * everything else (prose, headings) becomes the task's description field.

New format: single YAML file with header fields at top level and an ordered blocks: list. See greatminds task show output and the packaged schema for the exact shape.

Usage: greatminds migrate-task --file path/to/task.md one file greatminds migrate-task --queue feature_dev all active in a queue greatminds migrate-task --all every .md task in .greatminds/ (active queues only by default; pass --include-terminal to also touch verified/, archive/, etc.)

Flags: --dry-run report what would be migrated; write nothing --keep-md leave .md alongside new .yaml --force overwrite existing .yaml if present

Best-effort: per-block fields are remapped where the canonical name changed (written_by→by, written_at→at, closed_by→by, closed_at→at). Unknown fields are preserved verbatim under their original key.

Usage:

greatminds migrate-task [OPTIONS]

Options:

  --file TEXT         single .md file to migrate
  --queue TEXT        migrate all .md in this queue
  --all               migrate every .md in active queues
  --include-terminal  with --all, also include verified/archive/stand_done/...
  --dry-run
  --keep-md           leave the original .md file in place
  --force             overwrite existing .yaml
  -h, --help          Show this message and exit.

greatminds notify-journal¶

Replay recent journal.ndjson lines and write inbox wake-up messages.

Called from a PostToolUse hook (claude/cursor). It is idempotent — a state file tracks the last processed offset so duplicate invocations are safe.

For each new journal entry, looks up which role should be woken via schema.yaml (the role whose claims_from contains the destination queue gets a wake message). Special-cases:

to=stand_done → notify TESTER for each task in evidence_for.
to=verified → notify ARCHITECT-REVIEWER (so it runs wake_check).

Usage: notify_from_journal [--project-dir

] [--canon-dir ] [--once]

By default scans only new lines since the last invocation. --once processes every line (useful for backfill).

Exit code is always 0 — failure to notify should never block the producer's tick.

Usage:

greatminds notify-journal [OPTIONS]

Options:

  --project-dir DIRECTORY  project root (default: cwd)
  --canon-dir DIRECTORY    canon data dir (default: packaged greatminds.data)
  --once                   replay ALL lines (backfill); default: only new
                           lines
  -h, --help               Show this message and exit.

greatminds plan¶

plan — ARCHITECT-PLANNER convenience: triage + plan + route in one go.

Atomic 4-step chain:

append-block triage on the inbox task
mv → feature_plan
append-block plan (with all required fields)
mv → per-scope queue (or feature_docs_review for --audit-only)

The chain stops at the first failing step and prints exactly where it stopped and what to do — never a silent partial failure.

Only ARCHITECT-PLANNER may run this command (the GREATMINDS_ROLE env var is enforced; refusing other roles up-front avoids ambiguity).

Usage:

greatminds plan [OPTIONS] ID

Options:

  --scope [backend|docs|ui]      [required]
  --assignee-role TEXT           [required]
  --base-commit TEXT             [required]
  --plan-kind [full|bugfix]      [required]
  --mode [A|B|C]                 [required]
  --stand-required [true|false]  [required]
  --stand-reason TEXT
  --body TEXT                    plan text (literal)
  --body-file TEXT               plan text: file path, or - for stdin
  --triage TEXT                  optional triage note
  --stop-at [plan]               stop after plan block; do not route to per-
                                 scope queue
  --audit-only                   READER audit (scope must be docs): no WRITER
                                 step — route straight to feature_docs_review.
  -h, --help                     Show this message and exit.

greatminds project¶

read-only view of project docs (PROJECT.md).

Usage:

greatminds project [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds project show¶

print coordination/PROJECT.md (read-only).

Usage:

greatminds project show [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds pty-launch¶

pty-launch [tool args...] — spawn TOOL in a pty we own.

Why: writing to /dev/pts/N as an unrelated process targets the slave side and shows up as terminal output (display), not input. The reason user keystrokes wake the agent is that the terminal emulator (xterm/gnome- terminal/…) writes to the master end of the pty, which routes to the slave's read-queue — i.e. the running process's stdin.

This launcher creates its own pty, runs TOOL inside it (slave fd as stdin/stdout/stderr), keeps the master fd, and proxies bytes between the user's terminal and the pty. Crucially it also exposes a unix socket at <COORDINATION_DIR>/.agent_registry/<role>.sock that any external process (coordd!) can connect to and write bytes — those bytes go straight into the master end and are seen by the agent exactly like user keystrokes.

The registry file <role>.json is updated to record the socket path so coordd knows where to push.

Usage in start_agent: pty-launch DEVELOPER claude --name DEVELOPER --permission-mode auto "$PROMPT"

Usage:

greatminds pty-launch [OPTIONS] ROLE EXEC_BINARY [TOOL_ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds report-upstream¶

greatminds report-upstream — file a bug against the upstream greatminds repo.

Three submission modes, configurable via --mode or coord.yaml: report.mode:

url Default. URL-encode the body into https://github.com/<repo>/issues/new?... and open it in the user's browser (also printed to stdout). Zero creds, zero side effects beyond a browser tab. gh Shell out to the local gh CLI (gh issue create); requires gh auth login already done. api-token POST to the GitHub REST API directly, using a PAT read from $<token_env> first, then .greatminds/PROJECT.env. No token is bundled in the PyPI artifact.

Designed for MAINTAINER use only — other roles file inbox/maintainer/ asks; MAINTAINER triages "our bug vs upstream" and invokes this command when the bug is upstream.

Usage:

greatminds report-upstream [OPTIONS]

Options:

  --title TEXT                  issue title (short)  [required]
  --body TEXT                   issue body text (inline)
  --body-file FILE              read body from FILE (use '-' for stdin)
  --severity [low|normal|high]  [default: normal]
  --label TEXT                  label to attach (repeatable)
  --mode [url|gh|api-token]     submission mode (overrides coord.yaml
                                report.mode)
  --dry-run                     print the assembled body to stdout and exit
  --no-diagnostics              skip auto-collected diagnostics (manual body
                                only)
  --project-dir DIRECTORY       override project root (default: cwd /
                                coord.yaml)
  -h, --help                    Show this message and exit.

greatminds restart¶

greatminds restart — idempotent fleet restart.

Restart the daemon if needed, ensure the tmux session exists, and relaunch eligible loop/chat agents whose registry entry is missing or dead.

systemctl --user is-active --quiet coordd; if not, start it.
tmux has-session -t <session>; if missing, shell out to greatminds launch --target tmux.
For each window in coord.yaml with a non-empty role, resolve .greatminds/.agent_registry/<role-lowercase>.json:
- missing / pid dead / no pid → relaunch eligible loop/chat panes with greatminds start-agent.
- driven and staged roles are skipped because coordd or the operator owns their next turn.
- alive → skip.
Wait 10s, then re-read each registry. A role passes if the file exists, pid is alive (os.kill(pid, 0)), and input_sock is present. Exit 0 if all roles pass; exit 1 otherwise.

Usage::

greatminds restart [--config <coord.yaml>] [--project-dir <dir>]

Linux + systemd-user only.

Usage:

greatminds restart [OPTIONS]

Options:

  --config FILE            path to coord.yaml (default:
                           <project>/coordination/coord.yaml)
  --project-dir DIRECTORY  override config.project_dir / cwd
  --bootstrap              soft canon refresh for alive agents. Pastes the
                           static `.greatminds/bootstrap.md` into the live
                           tmux pane via bracketed paste, then submits with
                           Enter. The agent keeps running — session-id files
                           are NOT touched, pid is NOT killed, claude --resume
                           / codex resume continuity is preserved. This is the
                           canonical post-PyPI-upgrade procedure: `pip install
                           -U greatminds && greatminds restart --bootstrap`.
                           Mutually exclusive with --reset.
  --reset                  destructive re-launch. SIGTERMs each alive pid and
                           clears claude/codex session-id files so the next
                           start-agent goes through the fresh-session path.
                           Use when the agent's context is unrecoverably
                           corrupt or a canon-format-incompatible version bump
                           requires a genuine state-bust. NOT the default
                           upgrade procedure — that's --bootstrap. Mutually
                           exclusive with --bootstrap.
  -h, --help               Show this message and exit.

greatminds setup¶

greatminds setup — bootstrap a project to use the coordination protocol.

Creates the runtime queue tree, copies the schema / COORDINATE.md and seeds the static bootstrap.md from the packaged greatminds.data directory, plus the inbox + plugin-overlay layout.

After this command, the project has everything it needs to run the fleet. Next steps:

edit <project>/coordination/coord.yaml to confirm project_dir + window list
fill in <project>/coordination/PROJECT.md tokens (project name, stand hosts, env paths, etc.)
run greatminds launch --target tmux to start the fleet

No bin/* shims are created. With greatminds installed in your env (pip, pipx, uv, poetry, pixi, conda), the unified greatminds binary lives on PATH; per-project shims are unnecessary.

Usage:

greatminds setup [OPTIONS]

Options:

  --project-dir DIRECTORY  project root (default: cwd)
  --force                  overwrite PROJECT.md if present. NOTE: coord.yaml
                           is NEVER overwritten by setup (init-style — delete
                           it first to regenerate). --force does not apply to
                           coord.yaml.
  --lang CODE              user-facing language for agents (chat replies,
                           console status, errors). ISO code: en, ru, zh, es,
                           fr, ja, etc. Internal artifacts (task fields,
                           journal, code) stay English regardless. Default:
                           en.
  --session NAME           canonical session name for the generated coord.yaml
                           (default: basename of project_dir). Must match
                           [A-Za-z0-9_.-]{1,64}; used as the systemd template
                           instance and the tmux session name.
  --pre-trust              pre-accept Claude Code's 'Do you trust this
                           folder?' and codex's 'Allow Codex to run' dialogs
                           for this project. Writes a single per-project entry
                           into ~/.claude.json and ~/.codex/config.toml;
                           idempotent; never touches other projects' entries.
                           Intended for toy / test fleets where TESTER /
                           STAND-KEEPER cannot walk dialogs interactively
                           (task 0076).
  -h, --help               Show this message and exit.

greatminds stand¶

singleton stand lease and deployment commands

Usage:

greatminds stand [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds stand deploy¶

Run the active lease's deploy profile and transition ready/down.

Coordd runs this automatically for a preparing lease; this command is the manual/operator entry to the same deploy engine.

Usage:

greatminds stand deploy [OPTIONS]

Options:

  --lease-id TEXT  active lease to deploy (must match state.yaml)  [required]
  --timeout FLOAT  kill the playbook after N seconds (rc=124)
  -h, --help       Show this message and exit.

greatminds stand down¶

Mark the stand down after a deploy or infrastructure incident.

MAINTAINER-only.

Usage:

greatminds stand down [OPTIONS]

Options:

  --reason TEXT  operational reason logged in state file  [required]
  -h, --help     Show this message and exit.

greatminds stand lease¶

Request a lease on the singleton stand.

Behavior: - On state=free: transitions free→preparing(lease_id); SK picks up the new lease on its next tick. - On state≠free: enqueues the request; the lease becomes active when SK releases the current one.

Returns the freshly-minted lease_id (UUID4) as the LAST line of stdout. Callers (test scripts, agents) capture this token; only the holder may release.

Usage:

greatminds stand lease [OPTIONS]

Options:

  --task TEXT                  product-task id this lease serves  [required]
  --worktree TEXT              path to the worktree coordd will deploy from.
                               Optional: defaults to the canonical per-task
                               worktree (.worktrees/<task_id>) and is auto-
                               created if absent, so review_session leases
                               (EXPLORER) need no raw git.
  --profile TEXT               registered deploy profile name from stand-
                               profiles.yaml  [required]
  --ttl-seconds INTEGER        override ttl (default: schema
                               lease.ttl_seconds_default)
  --deploy-prerequisites-only  run only prerequisite-tagged profile tasks
                               before the holder performs the actual deploy.
                               Overrides the profile-level setting.
  --profile-approval TEXT      explicit approval marker required by high-risk
                               profiles
  -h, --help                   Show this message and exit.

greatminds stand profiles¶

inspect and validate stand profile registry

Usage:

greatminds stand profiles [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds stand profiles doctor¶

Validate registry tokens and referenced YAML playbooks.

Usage:

greatminds stand profiles doctor [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds stand profiles list¶

List registered stand profiles for this project.

Usage:

greatminds stand profiles list [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds stand ready¶

Transition a prepared lease to ready and notify the holder.

Refuses the transition unless a deploy marker exists at <coord>/.stand/deploy-<lease_id>.log. The marker proves coordd invoked the YAML deploy profile before setting the lease ready.

Usage:

greatminds stand ready [OPTIONS]

Options:

  --lease-id TEXT  lease that just finished preparing  [required]
  -h, --help       Show this message and exit.

greatminds stand reclaim¶

Reclaim an expired lease whose holder is no longer alive.

A stale lease (a crashed holder past its ttl_seconds) otherwise permanently locks the singleton — release is holder-only and there was no reaper. reclaim is restricted to STAND-KEEPER / ARCHITECT-PLANNER (the stand owners) and MAINTAINER (whose contract carries reclaim_stale_stand_lease_past_ttl_with_dead_holder as a recovery duty); it refuses to clobber a live, in-TTL lease OR a lease whose holder pid is still alive: it only frees a lease that is BOTH past its TTL AND held by a dead/absent agent.

Usage:

greatminds stand reclaim [OPTIONS]

Options:

  --lease-id TEXT  lease to reclaim (default: the active lease)
  -h, --help       Show this message and exit.

greatminds stand release¶

Release the active lease and promote the next queued lease.

Only the holder may release. The CLI rejects with exit_code=3 if --lease-id doesn't match the current active lease. Result is a CLOSED ENUM (pass/fail/partial) — no prose channel; TESTER's observations live exclusively in the product-task's tests block.

If the holder mismatches but the lease_id is in the queue, the requester is cancelling a pending request (state file removes the queue entry; no state transition).

Usage:

greatminds stand release [OPTIONS]

Options:

  --lease-id TEXT               lease_id token returned by `stand lease`
                                [required]
  --result [pass|fail|partial]  machine-readable resolution status (NOT a
                                report)  [required]
  -h, --help                    Show this message and exit.

greatminds stand status¶

Print the singleton stand resource state.

Reads .greatminds/.stand/state.yaml (creates a synthetic empty-state view when the file doesn't exist yet) and prints a compact human-readable summary: state, active lease (if any), queue contents, and the last few transitions.

Read-only. Use stand lease, stand ready, stand release, stand down, and stand up for mutations.

Usage:

greatminds stand status [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds stand up¶

Recover a down stand and resume queue processing.

MAINTAINER-only.

Usage:

greatminds stand up [OPTIONS]

Options:

  --reason TEXT  resolution note  [required]
  -h, --help     Show this message and exit.

greatminds start-agent¶

start_agent — launch an agent for a coordination ROLE in a given TOOL.

The public entry point is the unified greatminds start-agent command. After setup, the selected tool process replaces this script via os.execvp.

Usage::

greatminds start-agent <ROLE> <TOOL> [--mode loop|chat] [extra tool args...]

ROLE Role key from schema.yaml > roles (DEVELOPER, ARCHITECT-PLANNER, UI-DEVELOPER, EXPLORER, TESTER, …).

TOOL One of the tools reported by greatminds agent tools.

What it does:

Resolve project root from $GREATMINDS_PROJECT_DIR (or cwd).
Resolve canon (packaged greatminds.data) via find_canon_dir.
Export GREATMINDS_ROLE, PROJECT_ROOT and source the optional $PROJECT/.greatminds/PROJECT.env (gitignored secrets file).
Manage the per-role registry under $PROJECT/.greatminds/.agent_registry/<role>.{json,session-id}: refuse to start if another agent is alive (unless GREATMINDS_FORCE=1); reuse the persistent session UUID for --resume semantics; rotate the UUID when GREATMINDS_FRESH=1.
Use the single static system prompt .greatminds/bootstrap.md (seeded from canon by setup) as the prompt; the agent reads its own contract from schema.roles.<GREATMINDS_ROLE>. On resume, replace it with a short "continue your tick" nudge.
Set the terminal title (OSC 0) unless GREATMINDS_START_AGENT_NOTITLE=1.
Per-tool branching:

claude Layered --plugin-dir (canon coordination-protocol → canon per-role → project overrides) and --mcp-config (canon → project local). New session: --session-id. Resume: --resume. -- separator before the prompt so the variadic --mcp-config doesn't eat it.

codex Uses the single machine Codex home for authentication (GREATMINDS_CODEX_HOME, inherited non-per-role CODEX_HOME, or ~/.codex). Reads role model/settings from .greatminds/.codex-home/<role>/ as config source material and passes them as -c overrides; it does not use --profile or a per-role auth home.

cursor Wrapped in systemd-run --user --slice=cursor.slice --scope with memory/CPU caps (cursor-agent leaks memory in long sessions). Sets GREATMINDS_REGISTRY_TOOL=cursor so pty-launch records the logical tool, not systemd-run.

By default the tool is wrapped through python -m greatminds.cli.pty_launch, which records an input socket so coordd can inject keystrokes from outside the terminal emulator. Disable with GREATMINDS_START_AGENT_NOPTY=1.

Usage:

greatminds start-agent [OPTIONS] ROLE
                       {claude|codex|cursor|cline|gemini|openhands} [EXTRA]...

Options:

  --mode [loop|chat]  loop = self-driving tick loop; chat = interactive
  --dry-run           print the effective config (role, tool, plugin dirs, mcp
                      layers, final argv) and exit 0 without writing to
                      .agent_registry/ and without exec'ing the tool.
  -h, --help          Show this message and exit.

greatminds stop-decide¶

Hook helper: decide whether the agent should keep ticking instead of stopping.

Invoked from claude's Stop hook and cursor's stop/subagentStop hooks. Receives JSON on stdin (mostly ignored). Looks at:

the role's inbox (anything pending?),
(optional) the role's claims_from queues.

If there is wake work, prints a JSON blob telling the host to continue the loop. Otherwise prints {} (allow stop).

Output format depends on the host:

claude {"decision": "block", "reason": "<text>", "systemMessage": "<text>"} cursor {"followup_message": "<text>"}

Exit code is always 0; the JSON on stdout is the signal the host reads.

Usage:

greatminds stop-decide [OPTIONS] ROLE

Options:

  --host [claude|cursor]          output schema (claude vs cursor)
  --project-dir DIRECTORY         project root (default: cwd)
  --canon-dir DIRECTORY           canon data dir (default: packaged
                                  greatminds.data)
  --phase [stop|user-prompt-submit]
                                  hook phase (user-prompt-submit fires at
                                  start of each USER turn for chat-mode
                                  roles).
  -h, --help                      Show this message and exit.

greatminds task¶

task-file CRUD (intake, mv, append-block, show, list, validate)

Usage:

greatminds task [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds task append-block¶

Usage:

greatminds task append-block [OPTIONS] {blocked|implementation|plan|reader_rev
                             iew|review|rollback|session_iteration|tests|triag
                             e}

Options:

  --id TEXT         [required]
  --field TEXT      key=value (repeat)
  --body TEXT       block body: literal text | @PATH (read file) | - (stdin)
  --body-file TEXT  block body file path (alias for --body @PATH; preserved
                    for orchestrator and old-CLI compat)
  -h, --help        Show this message and exit.

greatminds task list¶

Usage:

greatminds task list [OPTIONS] QUEUE

Options:

  --json      emit a machine-readable JSON array (id/title/queue/file).
  -h, --help  Show this message and exit.

greatminds task mv¶

Usage:

greatminds task mv [OPTIONS] ID TO_QUEUE

Options:

  --reason TEXT
  -h, --help     Show this message and exit.

greatminds task new¶

Usage:

greatminds task new [OPTIONS]

Options:

  --stream [product|review_session]
                                  [required]
  --title TEXT                    [required]
  --reporter TEXT
  --priority [high|low|normal]
  --kind TEXT                     product:
                                  bugfix|docs|feature|ops|release|research
  --scope TEXT                    product:
                                  backend|docs|release|research|stand|ui
  --hosts TEXT                    list of hosts; repeat the flag or comma-
                                  separate values
  --evidence-for TEXT             task ids this run is evidence for; repeat or
                                  comma-separate
  --mode [A|B|C]
  --target-functionality TEXT
  --scenarios TEXT                scenario IDs; repeat or comma-separate
  --description TEXT              literal | @file | - (stdin)
  --in-queue TEXT                 destination queue (default depends on
                                  stream)
  --seq TEXT                      override numeric id prefix
  --reason TEXT                   journal reason
  -h, --help                      Show this message and exit.

greatminds task paths¶

Usage:

greatminds task paths [OPTIONS] [ID]

Options:

  -h, --help  Show this message and exit.

greatminds task show¶

Usage:

greatminds task show [OPTIONS] ID

Options:

  -h, --help  Show this message and exit.

greatminds task validate¶

Usage:

greatminds task validate [OPTIONS] ID

Options:

  --id TEXT    (back-compat) task id — same as the positional ID
  --file TEXT  explicit path to a .yaml task file
  -h, --help   Show this message and exit.

greatminds task withdraw¶

Usage:

greatminds task withdraw [OPTIONS] ID

Options:

  --reason TEXT  why the task is being withdrawn / cancelled  [required]
  -h, --help     Show this message and exit.

greatminds update¶

greatminds update — single-command upgrade of CLI + daemon + agents.

Three moving parts to keep in sync after a release:

The package itself in the venv where greatminds is installed (typically the project's .venv/ from uv add greatminds or pip install greatminds).
The systemd-user daemon greatminds-daemon@<project>.service.
The tmux agents restarted via greatminds restart.

This command runs all three in one pass, with a self-replacement step (os.execv) between phase 1 and the rest so the new code drives the daemon and agent refresh. --post-pip skips package installation and refreshes only daemon/agent state.

CLI surface::

greatminds update                  # full path: pip + daemon + agents
greatminds update --post-pip       # skip pip; daemon + agents only
greatminds update --check          # report would-be changes, no actions
greatminds update --dry-run        # alias of --check
greatminds update --major          # allow major-version bump

Usage:

greatminds update [OPTIONS]

Options:

  --post-pip      skip pip; only run daemon + agent restarts (idempotent
                  recovery mode).
  --check         report what would change; no actions.
  --dry-run       alias of --check.
  --major         allow major-version bump (default: refuse).
  --project TEXT  project name for `greatminds daemon restart` (default:
                  coord.yaml session).
  -h, --help      Show this message and exit.

greatminds wake-check¶

Report blocked tasks ready to wake, malformed deps, and deadlock cycles.

Usage: greatminds wake-check [--project-dir

] [--canon-dir ] [--quiet]

Scans /.greatminds/feature_blocked/*.{yaml,md}. For each: - parses the latest blocked block; - validates dependency entries match <queue>/<id>.{yaml,md}; - checks each referenced file actually exists; - flags tasks whose ALL deps exist AND none of those deps is itself in a wait state (active blocked queue) → READY TO WAKE.

Also detects: - malformed deps (wrong format or unknown queue); - deadlock cycles (A blocked on B, B blocked on A, etc — DFS over the feature_blocked dependency graph); - tasks with no blocked block (orphans).

ARCHITECT-REVIEWER is expected to run this at the start of every tick and act on ready-to-wake / cycle / malformed findings. wake_check never moves files.

Exit code: 0 always (informational).

Usage:

greatminds wake-check [OPTIONS]

Options:

  --project-dir DIRECTORY  project root containing .greatminds/ (default: cwd)
  --canon-dir DIRECTORY    canon data dir (default: packaged greatminds.data)
  --quiet                  suppress no-findings output
  -h, --help               Show this message and exit.

greatminds watchdog¶

Read-only watchdog for the coordination filesystem.

Reports: - orphaned intent files older than schema.watchdog.intent_orphan_seconds - tasks in active queues older than task_stale_in_active_queue_seconds - tasks in review queues older than task_stale_in_review_queue_seconds - registry entries whose pid is no longer alive

ARCHITECT-REVIEWER is expected to run this at the start of every tick and follow up on flagged items. The watchdog never moves files or alters state.

Exit code: 0 always (informational tool). --quiet only prints sections with findings.

Usage:

greatminds watchdog [OPTIONS]

Options:

  --project-dir DIRECTORY  project root containing .greatminds/ (default: cwd)
  --canon-dir DIRECTORY    canon data directory (default: packaged
                           greatminds.data)
  --quiet                  only print sections with findings
  -h, --help               Show this message and exit.

greatminds worktree¶

per-task git worktree lifecycle.

Usage:

greatminds worktree [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds worktree assert-drained¶

Exit non-zero if any feature_* queue is non-empty.

Deploying the worktree feature on top of a non-drained pipeline can produce unmergeable state. MAINTAINER runs this before rebuilding the wheel; non-zero refuses the run with the list of in-flight tasks per queue.

Usage:

greatminds worktree assert-drained [OPTIONS]

Options:

  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree create¶

Create a worktree for TASK_ID (idempotent).

Usage:

greatminds worktree create [OPTIONS] TASK_ID

Options:

  --base TEXT              Override base commit (default: task's
                           plan.base_commit, then main HEAD).
  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree list¶

List active worktrees.

Usage:

greatminds worktree list [OPTIONS]

Options:

  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree merge¶

Merge task/TASK_ID into main with the policy strategy.

Usage:

greatminds worktree merge [OPTIONS] TASK_ID

Options:

  --summary TEXT           Commit message suffix.
  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree path¶

Print the worktree path for TASK_ID.

Self-contained substitute for $GREATMINDS_TASK_WORKTREE: an implementer agent or STAND-KEEPER's rsync wrapper invokes cd "$(greatminds worktree path <task-id>)" to enter the task's isolated tree.

Usage:

greatminds worktree path [OPTIONS] TASK_ID

Options:

  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree prune¶

Remove worktrees whose task_id is not in any active queue.

Usage:

greatminds worktree prune [OPTIONS]

Options:

  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree refresh¶

Refresh TASK_ID's worktree from the current default branch.

Usage:

greatminds worktree refresh [OPTIONS] TASK_ID

Options:

  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree remove¶

Remove the worktree for TASK_ID.

Usage:

greatminds worktree remove [OPTIONS] TASK_ID

Options:

  --force
  --project-dir DIRECTORY
  -h, --help               Show this message and exit.