> your AI agent picks dependencies from memory; give it dated facts — try starlog.dev ↗ vet your agent's deps ↗ vibe-coding is fine. vibe-importing isn’t. — try starlog.dev ↗ vibe-importing isn’t fine ↗ your agent has never seen your private packages — try starlog.dev ↗ facts for private packages ↗ a linter for the dependencies your AI agent picks — try starlog.dev ↗ a linter for agent deps ↗ whois is redacted, cdns mask the rest — get the real operator — try whoisgeni.us ↗ who really runs that domain ↗ domain attribution that shows its work — full evidence chain — try whoisgeni.us ↗ domain intel w/ evidence ↗

← Back to Articles

Agenttrail: A Markdown-Based Coordination Protocol for Multi-Agent Coding Workflows

[ View on GitHub ]

Agenttrail: A Markdown-Based Coordination Protocol for Multi-Agent Coding Workflows

Hook

Your AI coding agents are stepping on each other's toes, and you're discovering it three git commits too late. Agenttrail treats your PLAN.md file as an append-only coordination log that survives version control and doesn't require learning LangGraph.

Context

The proliferation of AI coding agents—Claude Code, Cursor, OpenAI Codex—has created a new operational problem: visibility. When a single agent runs, you can watch terminal output. When three agents collaborate on different modules, you're juggling log files, trying to reconstruct who changed what from git blame timestamps, and discovering conflicting assumptions only when tests fail.

Existing observability solutions assume you control the agent execution layer. LangSmith wants you to instrument your LangChain code. OpenLIT traces API calls but has no concept of filesystem intent. Weight & Biases tracks training runs, not whether your authentication module got implemented. Agenttrail takes a radically different approach: treat agents as black boxes observable only through their filesystem footprints and opt-in log streams. It doesn't execute, approve, or coordinate work—it watches what happened and reconstructs a mental model you can reason about. The result is a dual-interface system: Map for project structure awareness, Kitchen for task-to-responsibility visualization, both running as localhost services that require zero cloud accounts.

Technical Insight

Kitchen Service

Map Service

file change

parsed graph

live updates

file events

log entries

task state

live updates

watch

tail

read

PLAN.md File

Map: Chokidar Watcher

Markdown Parser

Map WebSocket Server

Map Static Frontend

Kitchen: Filesystem Watcher

Provider Log Tailer

Multi-Source Parser

Kitchen WebSocket Server

Three.js 3D Renderer

~/.codex/sessions

~/.claude/logs

.office/kitchen.json

System architecture — auto-generated

Agenttrail's core architectural insight is passive observation through stable conventions. The Map component centers on a markdown DSL using fragment identifiers as stable component IDs. Here's what that looks like in practice:

## Authentication Module {#auth-module}
**Status:** In Progress  
**Owner:** claude-3-opus  
**Dependencies:** #database-schema, #user-model

- [x] JWT token generation
- [x] Password hashing with bcrypt
- [ ] OAuth2 provider integration
- [ ] Session management

## Database Schema {#database-schema}
**Status:** Complete  
**Owner:** codex-davinci  
**Last Updated:** 2025-01-15T14:32:00Z

Agents update this PLAN.md file as they work. Map runs a chokidar filesystem watcher that detects changes, parses the markdown structure, and broadcasts updates via WebSocket. The fragment ID syntax ({#auth-module}) provides stable references that survive reordering—critical when multiple agents append sections concurrently. The dependency graph (#database-schema) enables Map to highlight blocking relationships without executing any workflow logic.

The implementation is deliberately dependency-light. Map's backend is a single Node.js file that binds a localhost HTTP server, serves static HTML, and polls the filesystem:

const watcher = chokidar.watch('PLAN.md', {
  persistent: true,
  ignoreInitial: false,
  awaitWriteFinish: { stabilityThreshold: 300 }
});

watcher.on('change', async (path) => {
  const content = await fs.readFile(path, 'utf-8');
  const parsed = parsePlanMarkdown(content);
  const graph = buildDependencyGraph(parsed);
  
  wsClients.forEach(client => {
    client.send(JSON.stringify({
      type: 'plan_update',
      components: parsed.components,
      graph: graph,
      timestamp: Date.now()
    }));
  });
});

The awaitWriteFinish configuration handles the messy reality of agents writing incrementally—wait 300ms after the last write event before parsing to avoid processing half-written sections.

Kitchen tackles a harder problem: inferring who's doing what when agents don't explicitly coordinate. It combines three data sources. First, provider-specific logs that get tailed in real-time:

const providerAdapters = {
  codex: {
    logPath: path.join(os.homedir(), '.codex/sessions'),
    parser: parseCodexSession
  },
  claude: {
    logPath: path.join(os.homedir(), '.claude/logs'),
    parser: parseClaudeTaskList
  }
};

function parseCodexSession(sessionFile) {
  // Codex stores JSON-lines with task metadata
  const lines = sessionFile.split('\n').filter(Boolean);
  return lines.map(line => {
    const event = JSON.parse(line);
    return {
      agent: 'codex',
      task: event.instruction,
      files: event.modified_files || [],
      timestamp: new Date(event.completed_at)
    };
  });
}

Second, filesystem events correlated by timestamp proximity. When Kitchen sees a file change within 5 seconds of a log entry mentioning that path, it attributes the change to that agent. Third, optional explicit metadata in .office/kitchen.json that defines responsibility boundaries:

{
  "chefs": [
    {
      "id": "claude-opus",
      "role": "Backend Chef",
      "responsibilities": ["src/api/**", "src/database/**"],
      "color": "#4A90E2"
    },
    {
      "id": "cursor",
      "role": "Frontend Chef",
      "responsibilities": ["src/components/**", "src/styles/**"],
      "color": "#E24A4A"
    }
  ],
  "dishes": [
    {"name": "Authentication System", "tasks": ["#auth-module"]},
    {"name": "User Dashboard", "tasks": ["#dashboard-ui"]}
  ]
}

This metadata feeds the Three.js visualization—chefs rendered as 3D avatars at stations, dishes moving along conveyor belts as tasks complete. The rendering loop maps abstract events to spatial metaphors:

function updateKitchen(state) {
  state.chefs.forEach(chef => {
    const station = scene.getObjectByName(`station-${chef.id}`);
    const activeTask = chef.currentTask;
    
    if (activeTask && !chef.previousTask) {
      // Chef started cooking - spawn dish model
      const dish = createDish(activeTask.name, chef.color);
      station.add(dish);
      animatePreparation(dish, activeTask.estimatedDuration);
    }
    
    if (activeTask && activeTask.status === 'complete') {
      // Move completed dish to conveyor
      const dish = station.getObjectByName(`dish-${activeTask.id}`);
      animateToConveyor(dish, state.conveyorBelt);
    }
  });
}

The separation of concerns is deliberate: Map handles declared intent through markdown, Kitchen infers actual behavior through log reconstruction. Neither tries to be the source of truth—that's your version control system. They're observation layers that help you reason about distributed agent activity without introducing coordination overhead.

Gotcha

The provider adapters are reverse-engineered and fragile. Claude and Codex don't publish stable schemas for their session logs—Agenttrail's parsers expect specific JSON structures that break when providers update their storage format. The repository's issues show this happening: Codex changed session metadata keys in November 2024, breaking discovery for two weeks until an adapter patch landed. If you're running bleeding-edge provider versions, budget time for debugging parser failures.

The responsibility inference is fundamentally heuristic. Kitchen attributes file changes to agents by correlating timestamps within a 5-second window—if two agents touch the same file in rapid succession, attribution goes to whoever logged an event closest in time. This produces wrong results in practice: concurrent edits get assigned to one agent, slow filesystem writes drift outside the correlation window, and manual edits you make get attributed to whichever agent happened to log something nearby. The explicit handoff metadata in kitchen.json helps, but that means you're manually configuring the choreography system instead of getting automatic discovery. For genuinely adversarial multi-agent scenarios—where you need to debug conflicting changes—this won't give you reliable forensics.

Verdict

Use if: You're running multiple AI coding agents on the same local codebase and drowning in terminal windows. The PLAN.md markdown convention alone justifies adoption—it's a zero-dependency coordination protocol that survives git operations and gives agents a shared scratchpad without orchestration frameworks. Teams doing multi-agent experimentation will appreciate the passive observation architecture that doesn't require instrumenting agent code or uploading transcripts to cloud platforms. The local-first design works airgapped and avoids vendor lock-in. Skip if: You're using cloud-hosted agents like Replit or Devin where you can't access local logs. Single-agent workflows don't need this—terminal output suffices. Windows users should wait for platform verification. Teams needing production-grade observability with query capabilities and retention should use OpenTelemetry exporters instead. The 3D kitchen visualization is either delightful or distracting depending on team culture—if spinning chef avatars feel like a technical flex rather than utility, stick with Map and ignore Kitchen entirely.