greatminds 2.3.1

File-based Claude/Codex agent coordination with driven roles, editable project config, runtime state, Ansible stand leases, and evidence gates

greatminds

File-based multi-agent coordination for agent fleets and task pipelines.

greatminds runs a fleet of Claude Code and OpenAI Codex agents on a shared filesystem-based finite state machine. Tasks flow through queues such as feature_inbox/, feature_plan/, feature_dev/, feature_test/, and verified/; a small coordd daemon nudges agents when input appears. There is no central broker and no database. Per-project setup writes editable project configuration under coordination/ and runtime/system state under .greatminds/; the per-user daemon can supervise multiple projects on one machine.

Quickstart

# install
pip install greatminds  # or: uv add greatminds

# bootstrap a project
mkdir -p /tmp/greatminds-demo
cd /tmp/greatminds-demo
greatminds setup --session myproject

greatminds supports two primary agent tools:

• claude: Claude Code. Used for chat, loop, and driven roles. Setup writes .claude/settings.local.json and installs configured Claude marketplace plugins for Claude-hosted roles.
• codex: OpenAI Codex. Used for chat and driven roles. Run codex login once for the machine account; generated files under .greatminds/.codex-home/{role}/ are role config sources, not auth homes.

Window modes in coordination/coord.yaml:

• chat: a live tmux pane for an operator-facing conversation.
• loop: a resident watchdog pane that wakes on its own timer.
• staged: a tmux pane with the start command pre-typed, so the operator starts that role manually when needed.
• driven: no live pane; coordd starts one Claude or Codex turn when work lands in the role's queue, inbox, or stand event stream.

Role-to-tool assignment lives in coordination/coord.yaml. Edit it after setup when you want different tools for different roles:

Role	Default tool	Default mode
ARCHITECT-PLANNER	codex	chat
MAINTAINER	claude	loop
LIVE-DEVELOPER	claude	staged
ARCHITECT-REVIEWER	codex	driven
DEVELOPER	claude	driven
UI-DEVELOPER	claude	driven
TECHNICAL-WRITER	codex	driven
TESTER	claude	driven
READER	claude	driven
EXPLORER	codex	driven

session: myproject
project_dir: /tmp/greatminds-demo
windows:
  - name: planner
    role: ARCHITECT-PLANNER
    tool: codex
    mode: chat
  - name: maintainer
    role: MAINTAINER
    tool: claude
    mode: loop
  - name: dev
    role: DEVELOPER
    tool: claude
    mode: driven
  - name: reviewer
    role: ARCHITECT-REVIEWER
    tool: codex
    mode: driven

Put machine-local project and stand variables in .greatminds/PROJECT.env. It is gitignored, sourced before agent launch, and passed to stand profiles as Ansible extra vars:

cat > .greatminds/PROJECT.env <<'EOF'
STAND_HOST=localhost
STAND_USER=violet
EOF

STAND_HOST=localhost is enough for a local smoke stand. For a remote stand, set STAND_HOST to an SSH config alias or a comma-separated list of aliases, and set STAND_USER to the remote account whose PATH should be used.

A stand is a singleton live environment. Agents lease it with greatminds stand lease; coordd deploys the leased worktree by running an Ansible playbook selected through coordination/stand-profiles.yaml. There is no global current profile. The current profile is chosen for each lease with greatminds stand lease --profile {profile}, stored in .greatminds/.stand/state.yaml as active_lease.profile, and resolved through the registry to a YAML file under coordination/stand-profiles/.

Setup seeds reference profiles named full-deploy, vite-dev, and smoke-only. Add project profiles by adding registry entries and YAML files. The used_for and default_for values are machine-readable tokens from the packaged schema copied to .greatminds/schema.yaml under stand_profile_registry; default_for tells roles which profile to choose for common lease purposes:

profiles:
  full-deploy:
    file: full-deploy.yaml
    purpose: Full deployed product validation on a stand.
    environment: stand
    used_for: [tester_validation, explorer_review, reviewer_validation]
    default_for: [feature_test, explorer, reviewer]

Inspect and validate the registry with:

greatminds stand profiles list
greatminds stand profiles doctor

For production, create an explicit registry entry with environment: production, requires_explicit_user_approval: true, and allowed_roles such as [ARCHITECT-REVIEWER, MAINTAINER]. Lease it only after approval:

greatminds stand lease \
  --task TASK_ID \
  --profile production \
  --profile-approval USER_APPROVED

A minimal smoke playbook looks like this:

---
- name: register stand node
  hosts: localhost
  gather_facts: false
  tasks:
    - name: add configured stand host
      ansible.builtin.add_host:
        name: "{{ STAND_HOST | default('localhost') }}"
        groups: stand_nodes
        ansible_connection: >-
          {{ 'local' if (STAND_HOST | default('localhost')) == 'localhost'
             else 'ssh' }}

- name: smoke stand
  hosts: stand_nodes
  gather_facts: false
  tasks:
    - name: remote shell works
      ansible.builtin.command: /bin/true
      changed_when: false

Then start the fleet:

# install the per-project daemon
greatminds daemon install
greatminds daemon start

# launch agents
greatminds launch --target tmux
tmux a -t myproject

The windows defined in coord.yaml boot inside one tmux session. Roles with mode: driven do not keep live panes; coordd starts one Claude or Codex turn when their queue, inbox, or stand-state event changes.

Key Concepts

• Queues: feature_inbox/, feature_plan/, feature_dev/, verified/ - task state is its directory.
• Roles: ARCHITECT-PLANNER, DEVELOPER, TESTER, and others - each role owns queues and a heartbeat file.
• Scenarios A/B/C: standard pipeline, intensive review, and UI rapid iteration.
• Stand: lease-backed Ansible deployment profiles prepare the singleton live environment.
• Stand gate: stand-required tasks need lease-backed live-stand evidence before review.
• Inbox: per-role mailbox for ask, info, and wake messages without moving tasks.

Documentation

Full documentation: https://veryviolet.github.io/greatminds/

Where to File Issues

Bugs in greatminds: https://github.com/veryviolet/greatminds/issues
Bugs in a project you use greatminds in: that project's issue tracker.

License

Apache-2.0. See LICENSE.