Run a flock of AI coding agents — each in its own git worktree and tmux session — supervised from one desktop app.
What is it? • How is this different? • Quick Start • Download • How It Works • Documentation
Four agents · four git worktrees, side by side — one working, one waiting for your input, one running commit hooks, one reviewed with checks green.
Staring at a terminal waiting for an AI agent to finish is mind-numbingly boring — so you run several at once, and then you have six terminal windows and no idea which one needs you. MindFlock exists to answer one question at a glance: which agent needs me right now?
MindFlock turns one repository into a fleet of parallel, isolated AI coding sessions. Each session is a git worktree (or clone) plus a tmux session running the coding-agent CLI of your choice — any agent, declared in a TOML file — surfaced in the desktop app as a live terminal with a guided commit → push → PR → merge workflow. An optional ingestion pipeline can watch your issue tracker (Shortcut, Jira, Linear, GitHub Issues, Asana) and reviewed pull requests, and spin up a ready-to-work session for each — automatically.
Parallel-agent orchestrators are a crowded category, and several of them are good. Here's an honest read on where MindFlock actually differs.
MindFlock |
Claude Squad |
Conductor |
Claude Code Agent Teams |
|
|---|---|---|---|---|
| Interface | Cross-platform desktop app + phone UI |
Terminal TUI | Native macOS app | Built into the CLI |
| Platforms | Linux, macOS, Windows (WSL2) | macOS, Linux | macOS only | Anywhere Claude Code runs |
| Agent CLIs | Any — declared in a TOML file |
Several, bundled (Claude Code, Codex, Gemini, aider, OpenCode) | Claude Code, Codex, Cursor, OpenCode | Claude only |
| Session isolation | git worktree + tmux | git worktree + tmux | git worktree | git worktree |
| Git workflow | one-click commit → push → PR → merge (gh ) |
commit + push branch | per-task diff + review | manual (agent runs git) |
| Agent-state detection | deterministic — provider-defined hooks (working / idle / needs-input) |
inferred from the tmux pane | built-in, per supported agent | Claude-native |
| Ticket → session ingestion | Shortcut · Jira · Linear · GitHub Issues · Asana |
— | — | — |
| PR-review → session ingestion | reviewed PRs become sessions |
— | — | — |
| Remote / phone control | tailnet + QR, full action bar |
— | — | — |
Comparison as of July 2026; these tools move fast. If a cell is out of date, please open an issue or PR and we'll correct it.
MindFlock is a ground-up parallel-agent workspace. A few things set it apart:
Provider-agnostic by design. A coding agent in MindFlock is just a TOML file — binary, launch args, prompt seeding, activity-detection hooks, model pricing — so it drivesanyCLI (Claude Code, Codex, Gemini, aider, OpenCode, or one nobody's heard of) with the same working / idle / needs-input detection and token + cost tracking. Adding an agent is a config change, not a patch.Work comes to the agents. MindFlock can turn tickets and code review into sessions on its own: it watches your issue tracker (Shortcut, Jira, Linear, GitHub Issues, Asana) for work assigned to you, and GitHub for PRs that came back with review comments, then provisions a worktree and launches a seeded agent for each — nothing typed.The whole git loop is guided. Every session carries a one-click commit → push → PR → merge action bar (viagh
) and live workflow-stage badges, so you drive the change home without leaving the app.Supervise from anywhere.mindflock serve tailscale
prints a QR code; the mobile UI carries the same guided action bar, so you can unblock an agent from your phone.
When another tool may fit better:
is a native macOS (SwiftUI) app — if you're Mac-only and specifically want a native client, it's a solid pick.ConductorClaude Code's built-in Agent Teams + worktrees are free and already installed. If you only ever use Claude and live in the terminal, you may not need a separate app.is a mature multi-agent TUI that also drives several CLIs. If you'd rather stay in the terminal than run a desktop app, it's the closer fit.Claude Squad
- 🎫
Ticket & PR-review ingestion— watches your issue tracker (Shortcut, Jira, Linear, GitHub Issues, Asana) for assigned work and GitHub for reviewed PRs, then provisions a workspace and launches a seeded agent session for each. - 🔌
Provider-agnostic— every coding-agent CLI is just a TOML file (Claude Code, Codex, Gemini, aider, OpenCode bundled; add your own). Shared hook-based activity detection (working / idle / needs-input) and token & cost tracking apply to all of them. - 🖥️
Desktop app(Electron) — a draggable terminal grid with Agent / Terminal / Diff / Queue tabs per session, workflow-stage badges, and guided next-step buttons, in a window that follows each OS's own chrome conventions (native traffic lights on macOS, frameless with our own – □ ✕ elsewhere). - 📱
Phone UI—
mindflock serve tailscale
prints a QR code; the mobile UI at/m
carries the same guided git action bar, so the full flow drives from a phone. Auth-token protected — never open to the LAN unauthenticated. - 🌳
Isolated workspaces— every session gets its own git worktree, so agents never step on each other (or on you). - 🔀
Guided git workflow— one-click commit → push → PR → merge, driven by thegh
CLI. - ⚡
Terminal-first, too— themindflock
CLI drives the same sessions as the app (new
,ls
,attach
,rm
,open
,events
), so terminal and UI stay one system. - 🧩
Extensible— shell hooks on every session event, aWS /api/events
stream, and in-process Python + ES-module addons.
Install first — one command — then, from zero to a supervised agent session (this CLI flow is verified in CI on every push by scripts/quickstart-verify.sh):
mindflock doctor # 1. everything installed + authenticated?
cd ~/code/your-repo # 2. the repo you want the agents to work on
mindflock serve # 3. start the server (the app can also do this for you)
mindflock new . -p "fix the failing tests" # 4. (new terminal) spawn a session
mindflock ls # 5. watch it: TITLE REPO STATUS ACTIVITY STAGE DIFF COST
Open the MindFlock desktop app — the session is a live terminal; each one
is an isolated git worktree, with Diff view and guided
commit → push → PR → merge buttons. mindflock attach <title>
drops your terminal into the same tmux session.
mindflock serve
binds localhost only; run mindflock serve tailscale
to opt
into phone/tailnet access — an auth token + QR code are printed, and scanning
the QR opens the phone UI at /m
.
Each button downloads the newest release · all versions, checksums, and the Python wheel
| What you get | Anything else? | |
|---|---|---|
| Windows | ||
MindFlock-Setup.exe — the app and the engine (which runs inside WSL2). |
||
| Set up WSL2 first — see the note below. With a working WSL2 distro in place, the installer does the rest. | ||
| macOS | ||
MindFlock.dmg (universal — Apple silicon & Intel). Drag to Applications. |
||
| Nothing. First launch offers Install the engine — one click, no terminal. | ||
| Linux | ||
MindFlock.AppImage . chmod +x it and run. |
||
| Same — first launch installs the engine for you. |
The app auto-starts the engine every time after that — no terminal, no manual steps. If the engine is missing, the app's waiting page says so and shows the exact command.
⚠️ Windows: finish setting up WSL2 before you run the installer
beforeyou run the installer
The engine runs inside WSL2, so a Linux distribution must be fully installed
and launchable first — not just wsl --install
half-run. In PowerShell:
wsl --install # if WSL isn't set up yet — then REBOOT your PC
wsl -l -v # verify a distro (e.g. Ubuntu) is listed
wsl # verify this drops you into a Linux shell (first run asks you to create a user), then type: exit
Only once wsl
opens a Linux shell should you run MindFlock-Setup.exe
. A partially set-up WSL — installed but with no distro, or with a reboot still pending — is the single most common Windows install failure.
These builds aren't from a paid developer account — what you'll see on first launch #
MindFlock has no Apple Developer ID or Windows Authenticode certificate (both are paid, per-year subscriptions). The macOS build is signed, but with a free self-signed certificate — enough to keep macOS from re-asking for folder permission on every launch, not enough to satisfy Gatekeeper. So on first launch:
macOS — "Apple could not verify MindFlock is free of malware."
That dialog has no Open button, and the old Control-click → Open shortcut was removed in macOS Sequoia. To open it anyway (you only do this once):
- Drag MindFlock into yourApplications folder and try to open it. The warning appears — clickDone to dismiss it. - Open the menu → System Settings…→ Privacy & Security. - Scroll down to the Security section. You'll see a line like*"MindFlock was blocked to protect your Mac."*with anOpen Anyway button next to it. Click it. - Confirm with Open Anyway again and authenticate with Touch ID or your password. MindFlock launches, and macOS remembers the choice — you won't be asked again.
Prefer the terminal? This does the same thing in one line:
xattr -dr com.apple.quarantine /Applications/MindFlock.app
The first time MindFlock reads a folder under Documents, Desktop, Downloads, or an external drive, macOS asks "MindFlock would like to access files…" — click Allow. Because the app is signed, that grant sticks; it won't ask again for that folder.
Windows— SmartScreen's "Windows protected your PC". Click** More info→ Run anyway**.** Linux**— no prompt; AppImages aren't signed by convention.
Every release ships a .sha256
beside each installer (and SHA256SUMS
for the Python artifacts), and the builds are produced in public by the Release workflow straight from the tag — so you can check both the bytes and what produced them.
Most people want the download buttons above. This section is the same thing spelled out, plus every other way in.
Two pieces: the server/CLI (runs the engine) and the desktop app
(the one client, Electron — electron/README.md). On
Windows the .exe
installs both; elsewhere it's two commands.
On Linux, macOS, or inside WSL on Windows (the Windows installer runs this for you, inside your default distro):
curl -LsSf https://raw.githubusercontent.com/MindFlock/MindFlock/main/install.sh | sh
No repo clone, no Python setup needed — the installer brings
uv (no root), installs the mindflock
command,
and finishes with mindflock doctor
so anything still missing (git, tmux,
claude
) is listed with the exact install command for your platform.
Note onit isn't a blind one — the uv installer it fetches is version-pinned and sha256-verified before it runs, and the requested branch/tag is resolved to a full commit SHA that is printed and pinned for the install, an audit trail for what actually ran. Threat model and disclosure contact:curl | sh
:[SECURITY.md].
Prefer your own tooling? (uv / pipx / from source) #
uv tool install "mindflock[web] @ git+https://github.com/MindFlock/MindFlock"
pipx install "mindflock[web] @ git+https://github.com/MindFlock/MindFlock"
git clone https://github.com/MindFlock/MindFlock
cd MindFlock
uv sync --group web
Use the download buttons, grab any past build from Releases, or build it yourself:
cd electron && npm install && npm run dist
It finds — and auto-starts — the server by itself.
| Requirement | Notes |
|---|---|
| OS | |
| Linux, macOS (Apple silicon & Intel), Windows via WSL2 (the app runs natively on Windows; the engine lives in WSL2 — native Windows has no tmux/PTYs) | |
git ≥ 2.17, tmux ≥ 2.4 |
|
On PATH ; checked, with versions, by mindflock doctor |
|
| A coding-agent CLI | claude (Claude Code) by default |
gh (GitHub CLI) |
|
| For the push/PR/merge workflow | |
| Optional | cursor (IDE integration), tailscale (phone access) |
ticketing service ─┐ ┌─ desktop app (Electron)
GitHub PR reviews ┴─► ingestion pipeline ─┐ ├─ phone UI at /m (tailnet QR)
▼ ▼
┌──────────────────┐
│ session engine │ git worktrees + tmux
│ (backend.*) │ + provider launch
└──────────────────┘
▲
FastAPI server (backend.web)
| Component | Package | What it does |
|---|---|---|
| Session engine | ||
backend.session , backend.config , backend.cmd , backend.log |
||
Instance lifecycle (start//resume/kill), git worktree management, tmux/PTY plumbing, persisted state in ~/.mindflock/ . |
||
| Server + UI | ||
backend.web |
||
FastAPI server + the UI the desktop app renders: draggable terminal grid, Agent/Terminal/Diff/Queue tabs per session, workflow-stage badges with guided next-step buttons, token/cost usage, IDE integration, phone UI at /m , addon framework. |
||
| Ingestion pipeline | ||
backend.ticket_ingestion |
||
| Polls your ticketing service (Shortcut, Jira, Linear, GitHub Issues, Asana) for assigned work and GitHub for reviewed PRs; validates, provisions a workspace, and launches a seeded agent session per ticket / per PR. | ||
| Provider framework | ||
backend.providers |
||
| Pluggable coding-agent CLIs (Claude built in; aider/codex and others bundled; add your own via TOML). Shared hooks-based activity detection, model pricing, and rolling token/cost usage history. |
Something not working? Run mindflock doctor
and check TROUBLESHOOTING.md — it's indexed by the exact error text the tool prints.
The desktop app auto-starts the server when it isn't running; these commands are for headless/manual use:
mindflock serve # localhost only (127.0.0.1) — the default
mindflock serve tailscale # bind 0.0.0.0: tailnet mobile URL + QR + auth token
mindflock serve --port 9000 # custom port (default 8765)
Run mindflock serve
from inside the git repository you want to manage — the
startup banner prints which repo that is (and warns if it's the MindFlock
checkout itself). mindflock doctor
(also served at GET /api/doctor
) checks every dependency and prints a platform-appropriate fix for anything missing.
In the app, + New creates a session (worktree + tmux + agent); click a
session to type into its live terminal. The phone UI lives at /m
(scan the startup QR).
With a server running, the same sessions can be driven straight from any
terminal — the CLI talks to the server's API (auto-discovered on port 8765, or
--host
/--port
/ MINDFLOCK_HOST
/MINDFLOCK_PORT
):
mindflock new # session on the current repo (title = basename)
mindflock new ~/code/webapp -p "fix the failing tests"
mindflock ls # TITLE REPO STATUS ACTIVITY STAGE DIFF COST (--json for scripts)
mindflock attach webapp # tmux attach to the agent's terminal (prefix ok; needs a real TTY)
mindflock rm webapp --yes # end a session, keep its worktree (prompts without --yes)
mindflock open webapp # open the workspace in the configured IDE
mindflock events --follow # live event stream (great for hook debugging)
See docs/cli.md for the full command reference.
Configure it from the web UI's ⚙ Settings dialog (Ticketing / Repository /
GitHub sections) — values are saved to ~/.mindflock/settings.json
(mode
0600
, never committed). No file editing needed.
python -m backend.ticket_ingestion # run from the repo root
For headless/scripted runs you can instead use a config.toml
(an optional advanced override): copy config.toml.example to
config.toml
and fill in your values. Every field resolves through
env var → ~/.mindflock/settings.json → config.toml → default
, so the
Settings UI, an environment variable, or the file all work.Or toggle it from the web UI sidebar (Ticket Ingestion bar), which runs
it as a managed subprocess and tails its log. The pipeline is a singleton per
directory (.mindflock-pipeline.lock
); a second copy exits cleanly.
Every session event (created, status/activity/stage changed, d, deleted…) flows through a server-side event bus with three extension seams:
Shell hooks— drop an executable in~/.mindflock/hooks/<event>/
(env vars + JSON envelope on stdin — e.g. a desktop notification when an agent needs input).WebSocket— subscribe an external tool to theWS /api/events
stream.In-process addons— a PythonAddon
- an ES module the UI loads generically (the bundlednotify addon is the worked example).
See docs/extensions.md for the full guide.
| Path | Contents |
|---|---|
~/.mindflock/ |
|
Engine config + session state (config.json , state.json , worktrees/ ) and (the web Settings store: API keys, repo/ticketing config, provider + platform settings; mode settings.json 0600 , never committed) |
|
~/.mindflock-assistant/ |
|
| Assistant workspace, provider TOMLs, pricing/usage caches, scroll-speed, exit markers | |
./config.toml |
|
Optional advanced override for the pipeline + workspace provisioning (gitignored; superseded by settings.json / env vars — see |
|
config.toml.example |
|
./state.json |
|
Pipeline dedup state (processed stories/PRs; different file from the engine's ~/.mindflock/state.json ) |
|
./workspaces/ |
|
Provisioned story/PR workspaces, _base_* canonical clones, _testmon_refresher |
|
./logs/ |
|
pipeline.log , ticket-ingestion.log |
See docs/configuration.md for the full reference.
uv tool uninstall mindflock
removes the venv and the mindflock
shim, but
not the worktrees MindFlock registered inside your repositories, nor the
activity hooks it merged into their .claude
/.codex
settings — which keep
firing (and keep re-creating ~/.mindflock-assistant
) after the engine is gone. Undo those first:
mindflock uninstall --dry-run # see exactly what would be removed
mindflock uninstall # worktrees, hooks, scratch files (keeps settings + history)
mindflock uninstall --purge # …and delete ~/.mindflock + ~/.mindflock-assistant
uv tool uninstall mindflock # finally, the engine itself
On macOS the desktop app additionally leaves /Applications/MindFlock.app
,
~/Library/Application Support/MindFlock
, ~/Library/Logs/MindFlock
and
~/Library/Preferences/ai.mindflock.desktop.plist
. Full details in docs/cli.md.
| Doc | Contents |
|---|---|
docs/extensions.md/api/events
WebSocket, in-process addons, window.mindflock
client APIdocs/configuration.mdconfig.toml
reference, ~/.mindflock/
~/.mindflock-assistant/
, environment variablesdocs/session-engine.mddocs/cli.mdmindflock
CLI: serve, doctor, uninstall, and terminal session control (new/ls/attach/rm/open/events)docs/web-api.mddocs/web-ui.mddocs/providers.mddocs/ingestion-pipeline.mddocs/development.md
git clone https://github.com/MindFlock/MindFlock
cd MindFlock
uv sync --group web --group dev # web = FastAPI server deps, dev = pytest
uv run mindflock doctor # checks git/tmux/gh/agent CLI
uv run mindflock serve # localhost:8765, from a repo you want to manage
Run the test suite (unit + property-based [hypothesis] + integration):
uv run pytest
See docs/development.md for the full test map and project layout.
Contributions are welcome — bug reports, docs fixes, and code alike. Please
read CONTRIBUTING.md first. There's no CLA to sign: just
add a Signed-off-by
line to your commits with git commit -s
, certifying you wrote the patch under the Developer Certificate of Origin.
Project status — solo maintainer.MindFlock is built and maintained by one person in evenings and weekends. It is offered as-is under Apache-2.0; issues and pull requests are read and reviewed on a best-effort basis, and there is no support SLA. Bug reports (withmindflock doctor
output) and PRs are very welcome — just expect a hobby-project response time.
If MindFlock is useful to you, a ⭐ helps other people find it.
Licensed under the Apache License 2.0 — free and open source.
The MindFlock name and logo are trademarks; a license to the code is not a license to the marks. See TRADEMARKS.md for the trademark policy.