CLI reference

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 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:

1. 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.)
2. Scan coordination/inbox// for new files. For each new file, find the role's active TTY from coordination/.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, nothing changes — agents still work via ScheduleWakeup polling, just with the old multi-minute latency. The daemon is purely additive (a "side-load"): killing it never breaks the pipeline.

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

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

Usage: coordd [--project-dir

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

For a long-lived install, run via systemd-user; see bin/coordd-install.

Usage:

greatminds coordd [OPTIONS]

Options:

  --project-dir DIRECTORY  project root containing coordination/ (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. migrate removes the deprecated singleton coordd.service if present.

Usage:

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

Options:

  -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 legacy singleton coordd.service

Usage:

greatminds daemon migrate [OPTIONS]

Options:

  --yes       confirm removal of legacy coordd.service
  -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 gate-check

Check stand-evidence gate for a product task.

Usage: gate_check [--project-dir

] [--canon-dir ]

may be the full id (e.g. 0123-foo) or just the seq (e.g. 0123).

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 → find stand_done/*.{yaml,md} whose stand_result.evidence_for (or the file's top-level evidence_for in the yaml-native shape) contains this task id. If commit hash in plan/implementation matches the stand_result.commit, output 'pass'. If a candidate exists but commit differs or result not in {pass, ok} → 'fail'. No candidate → 'missing'.

Both the legacy fenced markdown shape and the yaml-native shape are supported; the reader picks the right parser per file.

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 launch

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

Reads <project>/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 greatminds-* 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>/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 command_START.yaml, COORDINATE.md, role docs (*.md) and templates/ 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-stand-history

Move legacy coordination/stand_done/* into coordination/archive/stand-history/ (0247 cleanup).

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

bin/migrate-task — convert legacy .md task files to the strict .yaml format.

Legacy format (current): 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 bin/task for the exact shape.

Usage: migrate-task --file path/to/task.md one file migrate-task --queue feature_dev all active in a queue migrate-task --all every .md task in coordination/ (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 (default: rename to .md.legacy) --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           don't rename original .md to .md.legacy
  --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:

1. append-block triage on the inbox task
2. mv → feature_plan
3. append-block plan (with all required fields)
4. 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 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 render-role

Render a role's bootstrap command with project tokens substituted.

ROLE is one of the keys under roles: in command_START.yaml (e.g. DEVELOPER, ARCHITECT-PLANNER, UI-DEVELOPER-FAST).

--project-dir points at an installed project containing coordination/PROJECT.md (default: current working directory). --canon-dir defaults to the packaged greatminds.data shipped with this wheel; pass to override (test fixtures, dev clones).

Prints the rendered bootstrap text to stdout; warnings about unresolved tokens go to stderr.

Usage:

greatminds render-role [OPTIONS] ROLE

Options:

  --project-dir DIRECTORY  project root containing coordination/PROJECT.md
                           (default: cwd)
  --canon-dir DIRECTORY    canon data dir (default: packaged greatminds.data)
  -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 coordination/PROJECT.env. No token is bundled in the PyPI artifact.

Designed for MAINTAINER use only — other roles file inbox/maintainer/ asks; MAINTAINER triages "наш баг vs апстрим" 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.

Replaces the temporary restart_fleet.sh bash crutch with a tested Python implementation. Same external behavior, same order:

1. systemctl --user is-active --quiet coordd; if not, start it.
2. tmux has-session -t <session>; if missing, shell out to greatminds launch --target tmux.
3. For each window in coord.yaml with a non-empty role, resolve coordination/.agent_registry/<role-lowercase>.json:
   • missing / pid dead / no pid → tmux send-keys Enter to (re)launch the agent. greatminds launch (since 0160) installs a bash wrapper-loop in each pane that prints press Enter to (re)start <ROLE>... and blocks at ``read -r _