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