Show HN：MindFlock——并行 AI 编程 Agent，各自运行在独立 Git worktree 中

四个 Agent · 四个 git worktree，并排运行——一个正在工作，一个等待你的输入，一个正在运行 commit hooks，一个已审查且检查全部通过。

盯着终端等待 AI Agent 完成任务无聊得令人麻木——于是你会同时运行好几个，接着就会面对六个终端窗口，完全不知道哪一个需要你。MindFlock 的存在就是为了让你一眼回答一个问题：现在是哪个 Agent 需要我？

MindFlock 将一个代码仓库变成一支并行、隔离的 AI 编程会话舰队。每个会话都是一个 git worktree（或克隆）加上一个运行你所选编程 Agent CLI 的 tmux 会话——任何 Agent 都可在 TOML 文件中声明——并在桌面应用中以实时终端呈现，附带引导式的 commit → push → PR → merge 工作流。可选的数据接入管道能够监控你的问题跟踪器（Shortcut、Jira、Linear、GitHub Issues、Asana）以及已审查的拉取请求，并为每一项自动启动一个可立即工作的会话。

并行 Agent 编排工具是一个拥挤的类别，其中也有不少优秀产品。以下是对 MindFlock 实际差异的坦诚对比。

| MindFlock | Claude Squad | Conductor | Claude Code Agent Teams
---|---|---|---|---
界面 | 跨平台桌面应用 + 手机 UI | 终端 TUI | 原生 macOS 应用 | 内置于 CLI
平台 | Linux、macOS、Windows（WSL2） | macOS、Linux | 仅 macOS | Claude Code 可运行的任何环境
Agent CLI | 任意 Agent——在 TOML 文件中声明 | 多种内置支持（Claude Code、Codex、Gemini、aider、OpenCode） | Claude Code、Codex、Cursor、OpenCode | 仅 Claude
会话隔离 | git worktree + tmux | git worktree + tmux | git worktree | git worktree
Git 工作流 | 一键 commit → push → PR → merge（gh） | commit + push 分支 | 按任务查看 diff 并审查 | 手动操作（Agent 运行 git）
Agent 状态检测 | 确定性——由提供商定义的 hooks（工作中 / 空闲 / 需要输入） | 从 tmux 窗格推断 | 内置，按受支持 Agent 提供 | Claude 原生
工单 → 会话接入 | Shortcut · Jira · Linear · GitHub Issues · Asana | — | — | —
PR 审查 → 会话接入 | 已审查 PR 自动成为会话 | — | — | —
远程 / 手机控制 | tailnet + QR，完整操作栏 | — | — | —

对比截至 2026 年 7 月；这些工具变化很快。如果表格中有内容已过时，请提交 issue 或 PR，我们会予以更正。

MindFlock 是一个从零构建的并行 Agent 工作区。以下几个特点使其与众不同：

• 设计上与提供商无关。 MindFlock 中的编程 Agent 只是一个 TOML 文件——包含二进制文件、启动参数、提示词预置、活动检测 hooks、模型定价等信息——因此它可以通过同样的工作中 / 空闲 / 需要输入检测以及 token 与成本跟踪，驱动 任何 CLI（Claude Code、Codex、Gemini、aider、OpenCode，或者某个无人听过的工具）。添加一个 Agent 是配置变更，而非代码补丁。
• 工作任务会主动来到 Agent 身边。 MindFlock 可以自行把工单和代码审查转为会话：它会监控问题跟踪器（Shortcut、Jira、Linear、GitHub Issues、Asana）中分配给你的工作，以及 GitHub 中收到审查意见的 PR；随后为每项工作创建 worktree，并启动一个已注入上下文的 Agent——无需输入任何命令。
• 完整 Git 闭环都有引导。 每个会话都提供一键式 commit → push → PR → merge 操作栏（通过 gh）以及实时工作流阶段标记，因此你无需离开应用即可完成变更交付。
• 可从任何位置监督。 mindflock serve tailscale 会打印二维码；手机 UI 带有相同的引导式操作栏，因此你可以通过手机为 Agent 排除阻塞。

何时其他工具可能更适合：

• Conductor 是一款原生 macOS（SwiftUI）应用——如果你只使用 Mac，并且特别希望采用原生客户端，它是一个可靠的选择。

• Claude Code 内置的 Agent Teams + worktrees 免费且已安装。如果你只使用 Claude，并且日常都在终端中工作，可能不需要单独的应用。

• Claude Squad 是成熟的多 Agent TUI，同样可以驱动多个 CLI。如果你宁可留在终端中，而不希望运行桌面应用，它会是更接近的选择。

• 🎫 工单与 PR 审查接入——监控问题跟踪器（Shortcut、Jira、Linear、GitHub Issues、Asana）中的已分配工作，以及 GitHub 上已审查的 PR；随后为每一项创建工作区并启动预置上下文的 Agent 会话。

• 🔌 提供商无关——每个编程 Agent CLI 都只是一个 TOML 文件（内置 Claude Code、Codex、Gemini、aider、OpenCode；也可添加你自己的）。共享的基于 hook 的活动检测（工作中 / 空闲 / 需要输入）以及 token 与成本跟踪适用于所有 Agent。

• 🖥️ 桌面应用（Electron）——可拖动的终端网格；每个会话均有 Agent / Terminal / Diff / Queue 标签页、工作流阶段标记和引导式下一步按钮。应用窗口遵循各操作系统自身的窗口样式约定（macOS 使用原生红黄绿窗口控制按钮，其他平台使用无边框窗口及自定义的 – □ ✕）。

• 📱 手机 UI——mindflock serve tailscale 会打印二维码；位于 /m 的手机 UI 带有相同的引导式 Git 操作栏，因此可通过手机完成完整流程。受到认证 token 保护——绝不会在未经认证的情况下向 LAN 开放。

• 🌳 隔离工作区——每个会话都有独立的 git worktree，因此 Agent 不会相互干扰，也不会影响你自己。

• 🔀 引导式 Git 工作流——通过 gh CLI 驱动的一键式 commit → push → PR → merge。

• ⚡ 同样以终端优先——mindflock CLI 与应用驱动相同的会话（new、ls、attach、rm、open、events），因此终端与 UI 始终是同一个系统。

• 🧩 可扩展——支持针对每个会话事件的 shell hooks、WS /api/events 流，以及进程内 Python 与 ES-module 插件。

请先安装——只需一条命令——然后从零开始创建一个受监督的 Agent 会话（该 CLI 流程会在每次推送时由 CI 通过 scripts/quickstart-verify.sh 验证）：

mindflock doctor                       # 1. 所有组件是否已安装并完成认证？
cd ~/code/your-repo                    # 2. 希望让 Agent 操作的仓库
mindflock serve                        # 3. 启动服务器（应用也可以为你完成这一步）
mindflock new . -p "fix the failing tests"   # 4. （新终端）创建一个会话
mindflock ls                           # 5. 观察状态：TITLE REPO STATUS ACTIVITY STAGE DIFF COST

打开 MindFlock 桌面应用——该会话会显示为实时终端；每个会话都是独立的 git worktree，并带有 Diff 视图以及引导式 commit → push → PR → merge 按钮。mindflock attach <title> 会让你的终端进入同一个 tmux 会话。

mindflock serve 仅绑定 localhost；运行 mindflock serve tailscale 可选择启用手机 / tailnet 访问——终端会打印认证 token 和二维码，扫描二维码即可在 /m 打开手机 UI。

| 你将获得什么 | 还需要其他操作吗？
---|---|---
Windows | MindFlock-Setup.exe——应用以及引擎（引擎运行在 WSL2 内）。 | 请先设置 WSL2——见下方说明。 安装并正常运行 WSL2 发行版后，安装程序会完成其余操作。
macOS | MindFlock.dmg（通用版本——支持 Apple silicon 与 Intel）。拖入 Applications 文件夹。 | 不需要。首次启动会提供 Install the engine——一键完成，无需终端。
Linux | MindFlock.AppImage。执行 chmod +x 后运行。 | 相同——首次启动会自动为你安装引擎。

此后，应用每次都会自动启动引擎——无需终端，无需手动步骤。如果引擎缺失，应用的等待页面会予以提示并显示准确命令。

⚠️ Windows：请在运行安装程序前完成 WSL2 设置

引擎运行于 WSL2 内，因此 Linux 发行版必须完全安装并可启动——不能只是半完成地运行过 wsl --install。在 PowerShell 中：

wsl --install     # 如果尚未设置 WSL——随后请重启电脑
wsl -l -v         # 确认列出了发行版（例如 Ubuntu）
wsl               # 确认这会进入 Linux shell（首次运行会要求你创建用户），随后输入：exit

仅当 wsl 能够打开 Linux shell 后，才应运行 MindFlock-Setup.exe。未完全设置的 WSL——已安装但没有发行版，或者仍待重启——是 Windows 安装失败最常见的单一原因。

这些构建版本并非来自付费开发者账号——以下是你首次启动时将看到的提示。

MindFlock 没有 Apple Developer ID 或 Windows Authenticode 证书（两者均为按年付费订阅）。macOS 构建版本_已签名_，但使用的是免费的自签名证书——足以避免 macOS 在每次启动时反复要求文件夹访问权限，但不足以满足 Gatekeeper 的要求。因此，首次启动时：

macOS——“Apple 无法验证 MindFlock 不含恶意软件。”

该对话框没有 Open 按钮，旧的 Control-单击 → Open 快捷方式已在 macOS Sequoia 中移除。若要仍然打开它（只需操作一次）：

1. 将 MindFlock 拖入 Applications 文件夹并尝试打开。警告出现后，点击 Done 关闭提示。
2. 打开菜单 → System Settings… → Privacy & Security。
3. 向下滚动至 Security 区域。你会看到类似 “MindFlock was blocked to protect your Mac.” 的一行文字，旁边有 Open Anyway 按钮。点击它。
4. 再次通过 Open Anyway 确认，并使用 Touch ID 或密码认证。MindFlock 将启动，macOS 会记住该选择——之后不会再次询问。

更喜欢终端？以下一条命令可完成同样的操作：

xattr -dr com.apple.quarantine /Applications/MindFlock.app

首次让 MindFlock 读取 Documents、Desktop、Downloads 或外接硬盘下的文件夹时，macOS 会询问：“MindFlock would like to access files…”——请点击 Allow。由于应用已签名，此授权会被保留；同一文件夹不会再次询问。

• Windows——SmartScreen 显示“Windows protected your PC”。点击 More info → Run anyway。
• Linux——不会出现提示；按惯例 AppImage 不会被签名。

每个版本都会在各安装程序旁提供 .sha256 文件（Python 构件则提供 SHA256SUMS），构建由公开的 Release workflow 直接从 tag 生成——因此你可以同时检查文件字节内容及其构建来源。

大多数人只需要使用上方下载按钮。本节将以明确文字说明同一安装方式，并列出其他所有可用方法。

系统由两部分组成：server/CLI（运行引擎）和 desktop app（唯一客户端，Electron——electron/README.md）。在 Windows 上，.exe 会同时安装两者；在其他平台上则需要两条命令。

在 Linux、macOS，或 Windows 的 WSL 环境中（Windows 安装程序会在默认发行版内部为你执行此命令）：

curl -LsSf https://raw.githubusercontent.com/MindFlock/MindFlock/main/install.sh | sh

无需克隆仓库，也无需设置 Python——安装程序会引入 uv（无需 root 权限），安装 mindflock 命令，并以 mindflock doctor 结束，将所有仍然缺失的组件（git、tmux、claude）及其对应平台上的准确安装命令列出。

关于 curl | sh 的说明： 这并不是盲目执行——它获取的 uv 安装程序会在运行前锁定版本并进行 sha256 校验；请求的分支/tag 会被解析为完整 commit SHA，该 SHA 会被打印并固定用于安装，从而留下实际运行内容的审计记录。威胁模型和漏洞披露联系方式请参见：SECURITY.md。

希望使用自己的工具链？（uv / pipx / 从源码安装）

# uv
uv tool install "mindflock[web] @ git+https://github.com/MindFlock/MindFlock"

# pipx
pipx install "mindflock[web] @ git+https://github.com/MindFlock/MindFlock"

# 从克隆仓库安装（贡献者）
git clone https://github.com/MindFlock/MindFlock
cd MindFlock
uv sync --group web

使用下载按钮、从 Releases 获取任意历史构建版本，或者自行构建：

cd electron && npm install && npm run dist

它会自行找到并自动启动服务器。

要求	说明
操作系统	Linux、macOS（Apple silicon 与 Intel）、通过 WSL2 使用的 Windows （应用原生运行于 Windows；引擎位于 WSL2 中——原生 Windows 没有 tmux/PTY）
git ≥ 2.17、tmux ≥ 2.4	位于 PATH 中；mindflock doctor 会检查它们及版本。
编程 Agent CLI	默认使用 claude（Claude Code）
gh（GitHub CLI）	用于 push / PR / merge 工作流
可选组件	cursor（IDE 集成）、tailscale（手机访问）

 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)

组件	包	作用
会话引擎	backend.session、backend.config、backend.cmd、backend.log	实例生命周期（启动 / 暂停 / 恢复 / 终止）、git worktree 管理、tmux/PTY 管道，以及保存于 ~/.mindflock/ 中的持久化状态。
服务器 + UI	backend.web	FastAPI 服务器，以及桌面应用所渲染的 UI：可拖动终端网格、每个会话的 Agent/Terminal/Diff/Queue 标签页、工作流

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 drives any CLI (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 (via gh) 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:

• Conductor is a native macOS (SwiftUI) app — if you're Mac-only and specifically want a native client, it's a solid pick.

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

• Claude Squad 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.

• 🎫 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 the gh CLI.

• ⚡ Terminal-first, too — the mindflock 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, a WS /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.

| 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

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

1. Drag MindFlock into your Applications folder and try to open it. The warning appears — click Done to dismiss it.
2. Open the menu → System Settings… → Privacy & Security.
3. Scroll down to the Security section. You'll see a line like "MindFlock was blocked to protect your Mac." with an Open Anyway button next to it. Click it.
4. 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 oncurl | sh: it 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: SECURITY.md.

Prefer your own tooling? (uv / pipx / from source)

# uv
uv tool install "mindflock[web] @ git+https://github.com/MindFlock/MindFlock"

# pipx
pipx install "mindflock[web] @ git+https://github.com/MindFlock/MindFlock"

# from a clone (contributors)
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/pause/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.

Ticket-ingestion pipeline

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, paused, deleted…) flows through a server-side event bus with three extension seams:

1. 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).
2. WebSocket — subscribe an external tool to the WS /api/events stream.
3. In-process addons — a Python Addon + an ES module the UI loads generically (the bundled notify 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/) andsettings.json (the web Settings store: API keys, repo/ticketing config, provider + platform settings; mode 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/architecture.md	System overview, components, data flow, on-disk state map
docs/extensions.md	Extension guide: shell hooks, /api/events WebSocket, in-process addons, window.mindflock client API
docs/configuration.md	config.toml reference, ~/.mindflock/ + ~/.mindflock-assistant/, environment variables
docs/session-engine.md	Instance lifecycle, git worktrees, tmux/PTY, provisioned mode
docs/cli.md	mindflock CLI: serve, doctor, uninstall, and terminal session control (new/ls/attach/rm/open/events)
docs/web-api.md	Complete HTTP + WebSocket API reference
docs/web-ui.md	Frontend guide: grid, tabs, stages, shortcuts, mobile, addons
docs/providers.md	Provider framework, adding a CLI via TOML, pricing & usage tracking
docs/ingestion-pipeline.md	Story + PR ingestion flows, state, testmon refresher
docs/development.md	Dev setup, test suite, project layout, known issues

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

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 (with mindflock 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.