Open Source

KodingX

Multi-Agent Software Factory

A filesystem-first protocol for orchestrating async multi-agent development. Turn your repo into a coordination hub where AI agents collaborate through structured markdown tasks and Definition-of-Done verification.

$npm i -g @lexaplus/kodingx
0.1.1
Version
agency/1.1
Protocol
6+
Agent Types
MIT
License

Event-Driven Architecture

Cursor orchestrates everything. Two MCP servers power the system — Terminal MCP spawns agents as parallel processes, Outbox Watcher MCP reacts to their output. The filesystem is the message bus.

Terminal MCPAgent Spawning

Cursor spawns Claude Code, Codex, and Gemini CLI as terminal processes. Each agent receives a prompt pointing to its inbox task file.

claude-code "Read your task at .agency/agents/claude-1/inbox/TASK-007.md"
Outbox Watcher MCPEvent Detection

A file watcher monitors .agency/outbox/ for new files. When an agent writes completion signals, the watcher notifies Cursor to trigger verification.

fs.watch(".agency/outbox/") → onFile → notify Cursor → verify → dispatch Playwright
Async Event Loop
1Decompose

Cursor breaks user request into atomic tasks on TASK_BOARD.md

2Dispatch

Tasks written to each agent's inbox/ directory

3Spawn

Terminal MCP launches agents as parallel processes

4Work

Agents read inbox, implement within scope, write to outbox/

5Detect

Outbox Watcher MCP detects new completion file

6Verify

Cursor dispatches Gemini (audit) → Playwright (E2E) → DoD check

7Close

All checks pass → task marked DONE on board

Decompose → Dispatch → Spawn → Work → Detect → Verify → Close↻
Filesystem = Message Bus
.agency/Protocol root directory
manifest.mdProject config & agent registry
tasks/Task definitions & assignments
TASK-001.mdStructured markdown task
agents/Agent directories
cursor-1/Per-agent workspace
inbox/Tasks & messages for this agent
outbox/Completed work & signals
dod/Definition-of-Done profiles
reviews/Audit & review artifacts
Cursor as Orchestrator
→
Decomposes

Breaks user request into atomic, scoped tasks on TASK_BOARD.md

→
Writes inbox/

Delivers task files to each agent's inbox directory

→
Spawns via Terminal MCP

Launches Claude Code, Codex, Gemini as parallel terminal processes

→
Reacts to outbox/

Outbox Watcher MCP triggers Cursor when agents signal completion

→
Dispatches verification

Sends Gemini to audit code, Playwright to run E2E tests

→
Closes the loop

Updates TASK_BOARD.md, archives review artifacts

Supported Agents

KodingX is agent-agnostic. Any AI tool that can read and write files can participate in the protocol. These are the built-in adapters.

Cursor

IDE
Builder

IDE-integrated agent for feature implementation with full codebase context

Claude Code

CLI
Builder / Auditor

CLI-native agent for complex reasoning, code review, and architectural decisions

Gemini CLI

CLI
Builder

Google's CLI agent for broad codebase changes and multi-file refactors

Codex

CLI
Builder

OpenAI's agent for code generation and transformation tasks

Kilo Code

IDE
Builder

Lightweight agent for scoped, single-file modifications

Playwright

E2E
Tester

E2E testing agent that validates acceptance criteria and UI flows

Task Lifecycle

Event-driven and async. Cursor orchestrates, agents work in parallel, filesystem events trigger verification. No polling, no dashboards — just files and processes.

NEWCursor decomposes user request into atomic tasks

The user says "Build auth system." Cursor analyzes the codebase, creates scoped tasks on TASK_BOARD.md with acceptance criteria, file boundaries, and DoD profiles.

ASSIGNEDTasks written to agent inboxes, processes spawned

Cursor writes task files to each agent's inbox/ directory, then uses Terminal MCP to spawn Claude Code, Codex, and Gemini CLI as parallel terminal processes — each with a prompt pointing to its inbox task.

IN_PROGRESSAgents work independently in parallel

Each agent reads its inbox task, implements changes within scoped file paths, and writes completion signals to its outbox/ directory. Agents run as isolated terminal processes with no awareness of each other.

READY_FOR_REVIEWOutbox Watcher MCP detects completion, triggers verification

The Outbox Watcher MCP detects a new file in outbox/ and notifies Cursor. Cursor dispatches Gemini CLI to audit the code, then Playwright to run E2E acceptance tests against the DoD profile.

DONEAll checks pass, task closed on board

Gemini audit passes, Playwright E2E passes, DoD criteria met. Cursor updates TASK_BOARD.md, archives review artifacts to .agency/reviews/, and picks up the next pending task.

CLI Commands

Everything is a command. No dashboards, no web UIs — just your terminal.

Initialize .agency/ directory in your repo
$agency init
✓ Created .agency/manifest.md
✓ Created .agency/tasks/
✓ Created .agency/agents/
✓ Created .agency/dod/
✓ Protocol agency/1.1 initialized
Create a scoped task with bounded file paths
$agency task new --title "Add auth" --scope "src/auth/**"
✓ Created TASK-007.md
  Scope: src/auth/**
  Status: NEW
  DoD: default.yaml
Assign task to a specific agent
$agency assign TASK-007 --agent cursor-1
✓ Assigned TASK-007 to cursor-1
✓ Wrote to agents/cursor-1/inbox/
  Status: NEW → ASSIGNED
Run Definition-of-Done checks
$agency verify TASK-007
✓ Scope check: PASS (no out-of-scope files)
✓ Tests: PASS (4/4 passing)
✓ Lint: PASS
✓ DoD: PASS
  Status: READY_FOR_REVIEW → DONE
View all tasks and agent status
$agency status
TASK-005  DONE         cursor-1   Add login page
TASK-006  IN_PROGRESS  claude-1   Refactor API
TASK-007  ASSIGNED     cursor-1   Add auth

Key Features

Built for teams that ship with AI agents — not against them.

Filesystem-as-API

The .agency/ directory replaces servers and databases. Everything is readable markdown and YAML — version-controlled and diffable.

Multi-Agent Orchestration

Coordinate Cursor, Claude Code, Gemini CLI, Codex, and more through inbox/outbox messaging. Each agent works in its own scoped context.

Definition-of-Done

YAML profiles define verification criteria — tests, lint, scope checks, and custom validators. No task closes without passing DoD.

Scope Enforcement

Every task declares allowed file paths. Agents cannot modify files outside their scope, preventing unintended side effects.

Risk Governance

Tiered approval workflows based on task risk level. High-risk changes require orchestrator sign-off before merging.

Parallel Execution

Multiple agents work on independent tasks simultaneously. The protocol handles coordination and conflict detection.

Tool Adapters

Built-in adapters translate the protocol for each agent type. Add custom adapters for any tool that can read and write files.

Git-Native

The entire protocol lives in your repo. Branch, merge, diff, and review agent coordination the same way you review code.

Start Building with Agents

Install the CLI, initialize the protocol, and let your AI agents collaborate through the filesystem.

$npm i -g @lexaplus/kodingx