README.md

How to Build an Automated AI Team with Cursor

如何在 Cursor 中搭建 AI 自动化团队

Just tell the PM what you need, go grab a coffee, and come back to review the results.

你只需要跟 PM 说清楚要做什么，然后去喝杯咖啡，回来验收成果。

📖 English | 📖 中文版

📜 Project Charter / 项目宪法 — CodeFlow = a lightweight AI Runtime / AI OS for multi-agent software development, driven by @cursor/sdk, consuming fcop-mcp (consumer-side; does not define fcop). 码流 = 面向多 Agent 协作开发的轻量级 AI Runtime / AI OS，用 @cursor/sdk 驱动、应用 fcop-mcp（消费方，不定义 fcop）。 Verbatim ADMIN charter quotes (5/9 10:48 + 10:51) live in design doc §0.0 / 完整原话见设计文档 §0.0

🚀 CodeFlow v2 — repositioning to AI Runtime / AI OS ([draft]): English overview (5 min) · 中文速读 (5 分钟) · Full design doc / 完整设计文档

🟡 v1.0 alignment pending — The current backend kernel ships as v0.1.0-rc.1 (internal preview, not published to npm/PyPI). It implements CodeFlow protocol v0.1 (5 schemas: agent / task / review / session / skill) with Review.decision="needs_human" and a human_approval sub-structure. These v0.1 concepts will be deprecated in v0.2 in favour of FCoP v1.0's Boundary capability — see FCoP issue #2 for the upstream v1.0 charter (7 abstractions, Boundary, etc.). CodeFlow v0.2 sprint 0 will fully align to fcop@>=1.0,<2.0. Release notes: docs/releases/v0.1.0-rc.1.md.

---

We published the methodology — How to Build an Automated AI Development Team in Cursor — and then built the tool to make it real.

我们先发布了方法论 — 如何在 Cursor 中搭建 AI 自动化开发团队 — 然后把它做成了产品。

CodeFlow (码流) is the production-ready tool born from that methodology. It turns the "filename as protocol" concept into a complete human-AI collaboration system: mobile command center + PC execution engine + multi-agent coordination.

码流（CodeFlow） 就是这套方法论的产品化落地。它把"文件名即协议"的理念变成了完整的人机协作系统：手机主控台 + PC 执行机 + 多角色自动调度。

Scope / 范围：FCoP vs this repo — The FCoP protocol and PyPI packages (fcop, fcop-mcp) are maintained in a separate GitHub repository (joinwell52-AI/FCoP). This repository is the CodeFlow / Bridgeflow tool line (Desktop, PWA, relay, etc.); it is not the FCoP source home. Boundary (中文) · README.zh — 本仓与 FCoP · README.en — This repo vs FCoP.

   

Why CDP / 为什么用 CDP

	OCR (legacy)	CDP — CodeFlow
Latency 延迟	300–800ms	10–15ms
Accuracy 精度	~90%	100%
Agent Detection 角色识别	Screenshot guess	DOM exact match
Setup 配置	Manual shortcut edits	Zero — auto-injected
Fallback 降级	None	Auto-falls back to OCR

Zero-config CDP injection: CodeFlow detects on startup whether Cursor has the debug port open. If not, it silently restarts Cursor with --remote-debugging-port=5253 — no manual shortcut edits, no config files, nothing.

零配置 CDP 注入：Desktop 启动时自动检测 Cursor 是否开启调试端口，若未开启则静默重启并自动注入参数，用户无需手动改快捷方式或任何配置文件。

---

From Theory to Tool / 从理论到工具

	Methodology 方法论	Product 产品
Repo	joinwell52	codeflow-pwa
What	How to name agents, define roles, route tasks via filenames	Desktop EXE + PWA + Relay + MCP Plugin
Core idea	TASK-date-seq-Sender-to-Recipient.md	Same protocol, automated end-to-end
Roles	PM / DEV / QA / OPS	3 team templates (dev / media / mvp)
Human role	Tell PM what to do	Phone sends task, PC executes

---

Screenshots / 产品截图

Desktop Panel / 桌面端控制面板

Cursor IDE — AI Agents at Work / AI Agent 工作中

PWA Mobile / 手机端

---

Quick Start / 快速开始

Desktop — download EXE (~35MB) and double-click:

• China: https://gitee.com/joinwell52/cursor-ai/releases
• GitHub: https://github.com/joinwell52-AI/codeflow-pwa/releases

PWA — open on phone and add to home screen:

• https://joinwell52-ai.github.io/codeflow-pwa/

For full documentation, see English | 中文.

---

Development / 开发

Want to build from source or contribute? See CONTRIBUTING.md.

# Desktop (Python 3.12, Windows)
cd codeflow-desktop
pip install pyautogui pyperclip pywin32 websockets winocr Pillow watchdog psutil
python main.py

# PWA (no build step)
python -m http.server 8080 -d web/pwa

Project structure:

codeflow-desktop/    # Desktop app (Python → EXE)
codeflow-plugin/     # Cursor MCP plugin
web/pwa/             # PWA (HTML/JS, no framework)
docs/                # Bilingual documentation
server/relay/        # WebSocket relay

---

Community / 社区

• Contributing Guide / 贡献指南
• Code of Conduct / 行为准则
• Security Policy / 安全策略
• Discussions / 讨论区

Further reading · FCoP protocol & field reports / 延伸阅读

• FCoP — File-based Coordination Protocol — the distilled protocol spec and essays behind CodeFlow's .cursor/rules/ design / CodeFlow .cursor/rules/ 背后的协议规范与随笔集
• When AI organizes its own work — a 4-AI-role team delivering 87 person-days in 17 days / 4 个 AI 角色在 17 天交付 87 人日
• An unexplainable thing I saw: the agent didn't just comply with rules — it endorsed them — an agent spontaneously wrote itself 4 FCoP memos on an unrelated task. 中文 · CSDN · Dev.to · Cursor Forum

---

License

MIT License. © 2026 joinwell52-AI

• Methodology: joinwell52-ai.github.io/joinwell52
• Product: github.com/joinwell52-AI/codeflow-pwa
• Changelog: CHANGELOG.md