FCoP — File-based Coordination Protocol

Let multiple agents work as a team. Keep tasks and deliveries in files.

New session, same project explanation? An agent says “done”, but where is the delivery record? FCoP keeps assignments, results, problems and reviews in your project's Markdown files, so people and the next agent can inspect the work and continue.

Multi-agent collaboration · Files as protocol · No complex infrastructure · Agent governance

协议原文：中文 · Specification: English · English · 简体中文 · Homepage

PyPI · fcop · MCP · fcop-mcp · MIT · Zenodo & citation

Run the minimal example · Connect Cursor / Codex · Installation FAQ

What do you get?

These files live in your project. Open them in an editor, inspect them with tools, and track suitable records in Git. Coordination records need no separate Redis, message queue or database. Agents keep using familiar clients such as Cursor and Codex.

Even when an agent is gone, the work remains.

Related MCP server: ToolSmith Agent MCP Server

Understand it in 30 seconds: you set the goal, PM leads

You are ADMIN, working with PM. PM breaks down the goal and assigns tasks to DEV, QA and OPS. Members execute and deliver reports; PM consolidates the results and reports back to you. Agents do not chat with each other; they collaborate through files.

The filename identifies a task or report, its header names sender and recipient, and its directory expresses task state. Agents follow the protocol to find their work, read the task, execute and report. This illustrates a PM-led team workflow; see file formats and version differences when needed.

Run a minimal example

PM assigns a text conversion to DEV, QA checks the actual result, and PM reads both reports before summarizing for ADMIN. The script uses independent clients to simulate three roles sequentially. No model or API key required. You need Python 3.10+ and Git.

git clone https://github.com/joinwell52-AI/FCoP.git
cd FCoP
python -m pip install "fcop==4.0.5"
python examples/team_workflow.py --output ./demo-runs

Open the workspace path printed by the script. You will find:

Open PM's summary and follow the files to the member deliveries and QA's check. The example completes delivery and keeps tasks in review, awaiting formal acceptance.

Full example code · Session handoff: English · 中文

Four questions before installation

1. Why should I install FCoP?

If you divide work among agents or often resume a project in a new session, FCoP gives tasks, deliveries and reviews a shared file record. The next person or agent can check progress with less manual reconstruction and retelling.

2. Do I import FCoP into my application code?

Usually no. Ordinary projects use the CLI and MCP; developers building their own integrations can use from fcop import Project.

3. Should I install it in Codex, Cursor or another agent client?

Yes. Configure fcop-mcp so your agent can create and claim tasks, submit reports, and record issues and reviews. It currently provides 25 Canonical MCP Tools / 6 read-only Core Resources.

4. What changes immediately after installation?

After connection, the client lists FCoP tools. Initialization creates <project>/fcop/. Execute a first task to get real TASK and REPORT files you can open. The example above also leaves QA's assessment and PM's summary.

Ask your AI to install FCoP

Paste this into Cursor Agent, Codex, or another coding agent with terminal and file access. The agent handles setup and checks the result.

Install FCoP for the coding client and project I am using. Follow:
https://github.com/joinwell52-AI/FCoP/blob/main/docs/ai-install.md
Run the environment checks, installation, configuration and verification yourself. Preserve my existing configuration and project state. Report what actually works; ask me only for a missing client/project choice or a required approval/reload.

MCP: give agents access to FCoP

python -m pip install "fcop==4.0.5" "fcop-mcp==4.0.5"
fcop tools

Configure a server in a client supporting local stdio MCP. This is a generic JSON example; see the AI installation guide for Codex-specific configuration.

{
  "mcpServers": {
    "fcop": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "fcop_mcp"],
      "env": {
        "FCOP_PROJECT_DIR": "/absolute/path/to/my-project"
      }
    }
  }
}

Replace the absolute paths with your Python interpreter and project path; forward slashes work on Windows. Reconnect and check the tool list, then follow the installation guide to initialize the project, adopt team rules and execute a task.

Full installation and client configuration

Historical 4.0.3 Cursor connection: 49 tools, 12 resources. The current 4.0.5 catalog has 25 tools and 6 read-only resources.

In use: CodeFlowMu

CodeFlowMu uses FCoP in a PM, DEV, QA and OPS development team, providing client integration, execution and progress views. It is distributed as a proprietary preview; FCoP's protocol and tools are MIT open source and independently usable.

FCoP is one approach to multi-agent collaboration, for teams that want tasks and deliveries to stay in local files.

Want to try it in your next multi-agent project? Star FCoP to keep it handy.

CLI — Local Setup, Inspect & Diagnose

CLI = Setup + Observe + Diagnose; MCP = Work.

Install & Verify

In an activated Python 3.10+ environment:

python -m pip install fcop

fcop version
fcop doctor
fcop init --root ./my-project
fcop status --root ./my-project
fcop validate --root ./my-project

For the optional MCP Tool Catalog:

python -m pip install fcop-mcp

fcop tools
fcop tools merge_branches --json

Once installed, the CLI can initialize, inspect, validate and diagnose locally and offline. doctor does not access the network or modify Host configuration. Package installation itself may need a package index; offline installation requires locally available packages. The CLI does not perform create_task, approval, Branch, merge or authorization work operations; use MCP or the Python API for those. Installing fcop does not create Host instruction files. Normal v4 workspace state belongs in <project>/fcop/, never in project-root AGENTS.md, CLAUDE.md or Cursor rules. Existing atomic initialization staging and failed-initialization evidence are preserved; customer files are never cleaned up automatically. migrate is a separate explicit legacy operation, not an automatic package-upgrade step. tools requires the optional MCP package and never starts a server or installs it automatically.

CLI reference · 中文 CLI 参考.

Reference, when you need it

How do files carry the protocol?

Files have agreed types, identities, senders, recipients and contents. Agents use those conventions to identify their work. Filenames, directories and file headers have distinct responsibilities.

An intuitive filename-routing example (Legacy v1–v3): TASK-20260915-001-PM-to-DEV.md is a task from PM to DEV; REPORT-20260915-001-DEV-to-PM.md is a report from DEV to PM. An agent with an assigned role can identify incoming files from the naming convention.

The current 4.0 implementation: new tasks live at fcop/_lifecycle/inbox/TASK-<uuid>.md, with sender: PM and recipient: DEV in the file header. The agent or caller reads the task fields and selects work for its established role. A filename-only search for to-DEV will not work because v4 names do not contain that segment. Reports live at fcop/reports/REPORT-<uuid>.md, with subject_ref and attempt_id linking the task and its execution attempt.

These placeholders explain layout; they are not complete runnable envelopes. Consult the 4.0 specification (English · 简体中文), current creation implementation and legacy filename grammar for the exact contracts.

Choose how to install

CLI and Python: one package

python -m pip install "fcop==4.0.5"
fcop version
fcop doctor
fcop init --root ./my-project
fcop status --root ./my-project

Python developers can then use from fcop import Project; see the complete example in the manual reference. Ordinary users do not need to import FCoP into application code.

MCP: give agents access to FCoP

python -m pip install "fcop==4.0.5" "fcop-mcp==4.0.5"
fcop tools

Configure a server in a client supporting local stdio MCP. This is a generic JSON example; see the AI installation guide for Codex-specific configuration.

{
  "mcpServers": {
    "fcop": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "fcop_mcp"],
      "env": {
        "FCOP_PROJECT_DIR": "/absolute/path/to/my-project"
      }
    }
  }
}

Replace command with the absolute path to the Python interpreter containing both packages, and set your project directory. Windows paths can use forward slashes. Reconnect the client to see 25 Canonical MCP Tools and 6 read-only Core Resources. Project initialization and team-rule adoption are separate steps; connecting MCP does not create a PM-led team or launch other agents.

Install from source

git clone https://github.com/joinwell52-AI/FCoP.git
cd FCoP
python -m pip install -e .
python -m pip install -e ./mcp
fcop version

The official installation route uses the Python packages above. This guide does not prescribe an unverified npm package or Node SDK. Node.js and other languages can integrate through an MCP client or implement the protocol themselves.

Implement the protocol yourself

You can build conforming tools from the formal specification (English · 简体中文) without using the Python reference implementation. Creating a few directories is not sufficient: field, transition, evidence, authorization, idempotency and recovery contracts must also be met. With the official toolkit, use fcop init to create the workspace.

macOS (Intel and Apple silicon): install CLI and MCP

FCoP supports macOS on both Intel and Apple silicon. The published wheels are platform-independent; Rosetta is not required. Use Python 3.10–3.13. The CLI works directly in Terminal, while MCP additionally requires a client that supports local stdio servers, such as Codex or Cursor.

Create a dedicated environment and install the matching Core/MCP pair:

python3 --version
python3 -m venv ~/.local/share/fcop/venv
~/.local/share/fcop/venv/bin/python -m pip install --upgrade \
  "fcop>=4.0.5,<4.1.0" \
  "fcop-mcp>=4.0.5,<4.1.0"

Verify the CLI and installed MCP catalog:

~/.local/share/fcop/venv/bin/fcop version
~/.local/share/fcop/venv/bin/fcop doctor
~/.local/share/fcop/venv/bin/fcop tools --json

The installed CLI provides all nine commands listed below: init, status, inspect, validate, tools, doctor, version, spec, and migrate. CLI setup and inspection do not require an MCP-capable AI client.

For MCP, configure the client with absolute macOS paths; do not use ~ inside client configuration:

{
  "mcpServers": {
    "fcop": {
      "command": "/Users/YOUR_NAME/.local/share/fcop/venv/bin/python",
      "args": ["-m", "fcop_mcp"],
      "env": {
        "FCOP_PROJECT_DIR": "/Users/YOUR_NAME/path/to/your-project"
      }
    }
  }
}

Replace YOUR_NAME and the project path, then restart or reconnect the MCP client. FCOP_PROJECT_DIR points to the project that will use FCoP, not to this source repository.

4.0.1 introduced create_branch, inspect_family and merge_branches; 4.0.5 exposes 25 canonical MCP tools and 6 read-only Core resources. Core owns atomic convergence, durable idempotency and recovery. Unfinished families return family_digest: null, merge_ready: false and structured reasons. The caller supplies the semantic conclusion. See the Branch merge contract and example / 中文合同.

Try it: create once, read from another client

In an activated Python 3.10+ virtual environment, install the published library:

python -m pip install "fcop==4.0.5"

Save this as demo.py and run python demo.py. It writes a real TASK, opens the workspace through a fresh Project instance, then retries the original request.

from pathlib import Path
from tempfile import TemporaryDirectory

from fcop import Project

with TemporaryDirectory(prefix="fcop-demo-") as directory:
    root = Path(directory) / "workspace"
    project = Project(root)
    workspace = project.create_workspace(protocol_version="4.0")
    request = dict(
        workspace_id=workspace["workspace_id"],
        operation_id="demo-create-1",
        sender="author", recipient="worker",
        subject="Inspect this handoff",
        body="Read the task and check the evidence before accepting delivery.",
    )
    first = project.create_task(**request)

    next_client = Project(root)
    state = next_client.inspect_state(task_id=first["task_id"])
    retry = next_client.create_task(**request)

    assert Path(state["path"]).is_file()
    assert retry["existing"] and retry["task_id"] == first["task_id"]
    print("State read from disk:", state["stage"])
    print("Same task after retry:", retry["task_id"] == first["task_id"])

State read from disk: inbox
Same task after retry: True

The example cleans up its temporary directory when it exits. Use your own project directory to retain the files. Retrying create_task with the same operation_id and normalized payload reuses its durable result; changing the payload is a conflict. This guarantee is specifically for task creation.

Continue with the 4.0 setup and version guide for a lasting workspace, lifecycle operations and the authorization needed to complete a task.

Give your agent the same operations through MCP

The optional adapter exposes FCoP to an MCP-capable client over stdio. Install it in the same activated environment:

python -m pip install "fcop==4.0.5" "fcop-mcp==4.0.5"

Add this entry to the client's MCP configuration. Replace both absolute paths; on Windows the command ends in .venv/Scripts/fcop-mcp.exe.

{
  "mcpServers": {
    "fcop": {
      "command": "/absolute/path/to/.venv/bin/fcop-mcp",
      "env": {"FCOP_PROJECT_DIR": "/absolute/path/to/new-workspace"}
    }
  }
}

In 4.0.5, initialize a new workspace with init_workspace(). Use its workspace_id and a unique operation_id with create_task, then inspect the TASK with inspect_task(task_id=...). Team/Solo/ME, seats, and Host session assignment are outside Base Protocol.

25 Canonical MCP Tools + 6 read-only Core Resources. The adapter routes to the same Python Core. Default initialization has no trusted authorization Profile: creation, claim and submission are available, but acceptance, rejection, reopening and archival need an explicitly adopted Profile and an issuer evaluator registered by the trusted host. A role name typed into a request cannot supply that authority. See the 49-to-25 migration guide for older clients.

MCP tool reference · Stable external Python example · Stable external MCP example. The full examples include an educational Profile; a real deployment must supply its own trust policy.

The 4.0 specification defines FCoP as a file-native agent behavior-governance protocol: files carry protocol, paths express current state, and events record transition history.

Roles such as PM, DEV, QA and OPS in dev-team come from a Team/Profile. The host adopts team rules; MCP supplies tools while the host runs and schedules models. Formal acceptance, rejection, reopening and archiving require an adopted Profile and trusted host authorization. Concurrent application-code changes need workspace isolation and integration review.

From a delivery claim to an accepted result

Each TASK follows an ordered lifecycle. In 4.0, entering active starts a new attempt, and submission links that attempt's REPORT. Acceptance then binds the review and authorization to the current evidence.

active → done is absent from 4.0. Reopening through reopen_task creates a new attempt for ordinary tasks as well as Branches. An old REPORT cannot satisfy a new attempt's submission gate. See the complete lifecycle and C1–C8 contracts · 中文规范.

Parallel work, with an explicit way to finish

Multiple ordered workflows can advance concurrently. A Branch is an ordinary TASK linked to one Root by branch_of; sibling Branches keep their own attempts, reports and reviews. Your Runtime decides who runs them and when.

Before a Root with Branches can be archived, FCoP checks completed Branches, their current REPORTs, a matching family_digest, a convergence REVIEW and separate Root archive authorization. A reopened Branch or changed REPORT invalidates stale convergence. Related writes share a short commit boundary; agents do not hold that lock while doing their work. This closes an evidence set; code integration remains the application's responsibility.

A small protocol inside a larger agent system

Another implementation should be able to preserve the same work semantics without copying a particular Python library, MCP tool list or product.

Read the design explanation: English · 简体中文. It develops the reasoning behind files, separate delivery and acceptance, parallel work, and the boundaries between FCoP, MCP and a Runtime.

Architecture principles: five full essays in Chinese, published September 10, 2026 and revised against 4.0:

1. Work beyond the model context: why files?

2. Extracting the minimal FCoP Core

3. Separating Core, Specification, Toolkit, Profile and Runtime

4. Parallel work through ordered task lifecycles

5. How FCoP, MCP, A2A and CodeFlowMu fit together

Series guide (中文) · All five essays (中文)

4.0.5 distributes nine bilingual rule modules through package-owned and MCP resources, with strict manifests and sequential, parallel and separate repository-development assemblies. Install → connect MCP → initialize workspace → use FCoP. FCoP owns <project>/fcop/, not project-root Host instruction files. Host projection, adoption, deployment and rollback are retired; redeploy_rules is Legacy v1–v3 only and rejects v4 with zero writes. Existing customer files stay unchanged. Rule resources / 规则资源.

Current Python packages: 4.0.5. Latest GitHub Release: 4.0.3. — 4.0.3 release. This repository contains the open protocol, the fcop Python implementation and the optional fcop-mcp adapter. Python 3.10+; no model API key is needed for the local example.

Discover FCoP: MCPServers introduction (简体中文) — a third-party directory for discovering and learning about FCoP. Registration details: Official MCP Registry — the server identifier, version and package metadata.

Papers, evidence and citation

These resources are directly accessible; reading the essay collection is optional.

Choose the archive matching the version you studied. The 4.0.5 software DOI identifies the current source archive; the preprint DOI identifies the paper and its frozen 4.0.3 evidence. The software update does not imply that the paper's experiments were rerun on 4.0.5.

Three repositories, three entry points

FCoP is independently usable under the MIT license. The product distribution has its own licensing and release schedule.

Star FCoP to bookmark the protocol and its implementation. To help it improve, share a reproducible integration issue, an example from your host, or a test of the protocol's public behavior through Issues or a pull request.

Versions and existing installations

• 4.0.0: Release notes · Changelog · Architecture decisions. Publication followed the recorded FCOP_4_STABLE_RELEASE_READY gate; users install the stable PyPI pair above.

• Release candidate: 4.0.0rc1 — retained as a historical prerelease.

• 3.x workspaces: retain their original semantics until explicit migration. Legacy specification EN · ZH. finish_task and legacy history tools remain discoverable but reject v4 workspaces.

• Legacy installation prompts: EN · ZH, also available at fcop://prompt/install. These are historical setup material; use the 4.0 guide above for the current version.