FCoP

FCoP — File-based Coordination Protocol

English · 简体中文

Even when the agent is gone, the work remains.

Tasks, deliveries, issues and review decisions become durable files that people, tools and the next agent can inspect. A session can end without taking the work record with it.

Ask AI to install · Manual reference · Architecture series (中文) · Architecture · Papers & citation

Stable version: 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.

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.

The AI installation guide covers dependencies, client configuration and a real task check. If the client needs approval or a reload, the agent will identify that step. Manual Python/MCP instructions remain below for reference.

Want to see a handoff first? Ask AI to run the session handoff example: English · 简体中文. Create a task and report, close the session, then read them from a fresh MCP session. No API key required; the result stays available for inspection.

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.3,<4.1.0" \
  "fcop-mcp>=4.0.3,<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.

See the minimum result

The visible outcome is not merely an installed package: formal work becomes inspectable files that another session can read. The linked handoff example verifies that result end to end.

Why put work outside the model?

“I have finished” is a statement in a conversation. A teammate still needs to know which assignment was attempted, what was delivered, who reviewed it and what remains unresolved. Keeping those facts only in a chat makes a handoff depend on reconstructing that chat.

FCoP gives formal work a shared representation: Markdown files with structured metadata, stable identities, explicit relationships and recorded state transitions. An agent can write them, a human can open them, and a script can validate them. The filesystem reference implementation needs no database or message broker.

Persistence makes a claim inspectable; it does not make the claim true. FCoP checks protocol relationships and gates. Reviewers evaluate the substance of the delivered work, and the host Runtime supplies execution, scheduling and permissions.

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

python -m pip install "fcop==4.0.3"

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="ME", recipient="ME",
        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

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

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

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.3 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 / 规则资源.

Papers, evidence and citation

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

Choose the archive matching the version you studied. The historical DOIs above are not identifiers for 4.0.0; use the versioned release and specification when discussing current behavior.

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.