AgentXFlow

AgentXFlow is an authoritative desktop application and Model Context Protocol (MCP) coordination daemon that enables multiple AI coding agents to collaborate concurrently on a single Git repository through isolated worktrees, write scope leases, automated machine verification gates, and a serialized FIFO merge queue.

Developed by harlixay7 • AgentXFlow by Viducia

Core Capabilities

• Isolated Git Worktrees: When an agent claims a task or masterplan chunk, AgentXFlow allocates an isolated Git worktree on disk. Agents work exclusively within their assigned worktree branch.
• Write Scope Leases: Agents declare intended file glob patterns (e.g. src/auth/**) before modifying files. Overlapping write patterns are detected and rejected.
• Attempt-Scoped Mutation Auditing: On task submission, the coordinator audits git diff against active scope leases for the current attempt. Acquiring missing scope leases cleanly resolves unreserved file violations on re-run.
• Automated Machine Verification Gates: The coordinator automatically executes verification profiles and machine evaluators (e.g. cargo test, npm test, type checks, lint checks) directly in the worktree. Criteria satisfaction is derived strictly from passing evaluator results (zero autonomous self-certification).
• Cryptographic Proof Bundles: Verified submissions generate an immutable ProofBundle sealed with a SHA-256 digest over task metadata, file diffs, and test outputs.
• Serialized FIFO Merge Queue: Verified candidate branches are integrated sequentially inside disposable integration worktrees, validated with post-merge tests, and advanced via atomic Compare-and-Swap (CAS) git update-ref operations.
• Multi-Masterplan Catalog & Single-Active Toggle: Manage multiple architecture specifications per project with an active/inactive toggle switch. Strictly enforces single-active mutual exclusion with conflict resolution modals, ensuring AI agents only see, decompose, and claim from the currently published masterplan.
• Dynamic Agent State Engine & Transparent Activity Heartbeats: Real-time evaluation of agent liveness (WORKING, IDLE, DISCONNECTED) derived from active task assignments and a 120-second activity window. Every inbound MCP tool call automatically refreshes agent timestamps—zero background timer loops required from LLM agents.
• Interactive Step Unclaiming & Worktree Cleanup: 1-click step recovery in both desktop UI and MCP gateway. Easily unclaim orphaned in-flight tasks from disconnected agents, reverting steps back to PENDING, releasing scope locks, and wiping isolated worktrees safely.
• Expanded Capacity Limits: Scalable masterplan decomposition supporting up to 100 structured steps and anti-hoarding chunk caps up to 8 steps per agent.
• Masterplan Hub: Single atomic preparation operation (prepare_masterplan) saves revisions, parses specification text, structures steps, and normalizes scopes with anti-hoarding active claim limits.

Architecture

+---------------------------------------------------------------+
|                          AI Agents                            |
|      Antigravity       Claude Code       Cursor       Codex   |
+---------------------------------------------------------------+
                                |
                                | (HTTP JSON-RPC / MCP 2024-11-05)
                                v
+---------------------------------------------------------------+
|                     AgentXFlow Coordinator                    |
|   - Masterplan Hub (Decomposition & anti-hoarding chunking)   |
|   - SQLite Database (Versioned migrations 1–11, WAL mode)     |
|   - Scope Engine (Multi-glob splitting & attempt auditing)    |
|   - Verification Engine (Machine evaluators & profile runner) |
|   - Merge Queue Engine (Serialized FIFO 3-way integration)    |
+---------------------------------------------------------------+
         |                      |                      |
         v                      v                      v
    Worktree #1            Worktree #2            Integration Worktree
 (task branch A)        (task branch B)           (merges to target)

Getting Started

Prerequisites

• Node.js 20 or higher
• Rust 1.80 or higher (cargo and rustc)
• Git CLI

1-Click Setup (Windows)

Double-click setup.bat (or run .\setup.bat in terminal). This script:

1. Verifies Node.js, Git CLI, and the Rust toolchain.
2. Installs required npm dependencies.
3. Compiles and type-checks the React frontend.
4. Validates Rust backend compilation.

Run the App

• On Windows: Double-click run.bat
• Or via terminal:

npm run tauri dev

Build Production Binary

npm run tauri build

Connecting AI Agents via MCP

AgentXFlow hosts a local Model Context Protocol (MCP) server conforming to the 2024-11-05 standard on http://127.0.0.1:7890/mcp.

Authentication tokens are generated dynamically per coordinator instance. Copy your active token from the MCP Gateway tab in the desktop application.

Supported Canonical AI IDEs & Tools

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "agentxflow": {
      "url": "http://127.0.0.1:7890/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <YOUR_COORDINATOR_TOKEN>"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json) / Claude Code

{
  "mcpServers": {
    "agentxflow": {
      "url": "http://127.0.0.1:7890/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_COORDINATOR_TOKEN>"
      }
    }
  }
}

Antigravity

The canonical coordinator skill definition is located at SKILL.md.

Standard Agent Startup Workflow

1. Context        -> Call agentxflow_current_context to discover active project, assigned task, and next action.
2. Register       -> Call agent_register(name="<Your_IDE>") with your canonical IDE platform (e.g. "Antigravity", "Claude Code", "Cursor").
3. Contract       -> Call project_context with project_id to fetch architectural rules and conventions.
4. Masterplan     -> Call masterplan_get. If UNSORTED, act as Master Architect: decompose raw specification into high-fidelity steps via masterplan_decompose.
5. Claim Chunk    -> Call masterplan_claim_chunk to allocate an isolated Git worktree (strictly capped by max_steps_per_agent).
6. Scope          -> Call scope_acquire with specific file globs before modifying code.
7. Implement      -> Make changes strictly inside your allocated worktree path and verify locally.
8. Step Evidence  -> Call task_complete_step with step_id and command verification evidence.
9. Submit & Gate  -> Call task_submit. The coordinator automatically executes verification profiles, audits scope mutations, generates ProofBundle, and enqueues to merge queue.
10. Milestone Handoff -> Inspect `next_action` in task_submit response:
                     - If `REPORT_TO_USER`: Interactive Milestone mode is active. Stop calling tools immediately, present a milestone walkthrough in chat, and wait for user confirmation.
                     - If `masterplan_claim_chunk`: Continuous Autonomous Swarm mode is active. Proceed immediately to claim the next chunk.
                     - If `FINAL_RELEASE_DELIVERY`: All masterplan steps are completed! As the final agent submitting Step N/N, build the production executable, generate the automated launcher (`run.bat`/`start.sh`), test that the app starts cleanly, create `USER_GUIDE.md` explaining the entire app, and present the full walkthrough to the user.

MCP Tools Reference

Testing & Quality Gates

# Run all backend unit and integration test suites
cargo test --manifest-path src-tauri/Cargo.toml

# Run the complete A-to-Z pipeline integration test
cargo test --test pipeline_a_to_z_test --manifest-path src-tauri/Cargo.toml

# Run the 30-scenario adversarial security and concurrency test suite
cargo test --test adversarial_suite_test --manifest-path src-tauri/Cargo.toml

# Run Rust linter with zero warnings allowed
cargo clippy --manifest-path src-tauri/Cargo.toml -- -D warnings

# Type-check and build production frontend bundle
npm run build

Repository Structure

• src-tauri/src/core/: Coordinator engine, state machines, canonical IDE resolution, and Tauri IPC commands.
• src-tauri/src/mcp/: Model Context Protocol (MCP 2024-11-05) Axum HTTP server with session derivation and tool registry.
• src-tauri/src/scope/: Glob pattern collision detection, pattern normalization, and attempt-scoped mutation auditor.
• src-tauri/src/verification/: Verification profiles, automated machine evaluators, and SHA-256 proof bundle generator.
• src-tauri/src/merge/: Serialized FIFO merge engine with disposable integration worktrees, automated background runner, and CAS ref updates.
• src-tauri/src/db/: Versioned SQLite migrations (1–11), connection pooling, and single-instance file lock.
• src/: React 19 / TypeScript workbench UI.

License

MIT (LICENSE)