greatminds

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

greatminds runs a fleet of Claude, Codex, or Cursor 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 coord.yaml; 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

# 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; each role starts in chat or loop mode according to that file.

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