ai-coord-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, OpenCode, etc.) when working with code in this repository.

What this is

An MCP server that is a shared coordination layer between two independently-launched AI coding assistants (Claude Code as coordinator, OpenCode as implementer, or any other MCP-capable clients). It is not an orchestrator: it never launches, manages, or talks to either AI process. It only exposes a task queue, a per-task message thread, and progress reporting, persisted as JSON files under .ai/coordination/. See README.md for the full tool reference, workflow conventions, and example session — don't duplicate that here, read it when you need the tool list or JSON shapes.

Commands

pnpm install
pnpm run build   # tsc -> dist/
pnpm run dev     # tsx src/index.ts, no build step
pnpm test        # node:test via tsx, runs every src/**/*.test.ts

Run a single test file: tsx --test src/storage/lock.test.ts. There's no separate lint script.

Architecture

Transport is stdio, and that is a deliberate, load-bearing choice, not an oversight. Each client (Claude Code, OpenCode) spawns its own copy of this server as a subprocess. "The same MCP server" therefore means the same storage directory (COORDINATION_DIR env var), not one running process — there is no shared memory between the two. This constraint shapes most of the non-obvious code in src/storage/:

• Every read goes straight to disk (readJson in json-file.ts) — there is no in-memory cache to go stale between the two processes.
• Every write goes through temp-file-then-rename (writeJsonAtomic) so a reader never observes a half-written file.
• src/storage/lock.ts is a cross-process mutex built on mkdir (atomic across OS processes, unlike an in-memory lock). Stale locks (crashed holder) are reclaimed after 10s; each holder writes a random ownership token so a holder that was merely slow (not dead) can't have its eventual release delete a lock someone else has since legitimately reclaimed — this ABA scenario is exactly what lock.test.ts exercises.
• Every task has a version counter (optimistic concurrency) checked in task-store.ts's mutateTask — the one place all task mutations flow through. mutateTask's callback can return false to declare a no-op (skip the version bump); update_progress relies on this so repeated progress pings on an already-in_progress task don't invalidate a caller's expected_version.
• Task ids are validated against /^task-\d{4,}$/ (src/schemas.ts) before being joined into any filesystem path — ids are always server-generated, so anything else is rejected outright rather than risking path traversal. Message ids are random UUIDs (randomUUID()), not path components, so they don't need this check.