Skip to main content

​
The Core Problem

When two developers use AI coding agents in parallel, those agents have no awareness of each other. They make independent decisions, edit the same files simultaneously, and contradict each other’s architecture — all without knowing it. The conflict surfaces at merge time.

​
The Three Layers

Enagrams solves this with three layers. Most teams never interact with layers 2 and 3 directly — the hooks do the work.

​
1. Automatic coordination (hooks)

IDE hooks fire on every relevant event. No manual MCP calls needed. 
New conversation
  → sessionStart hook fires
  → Agent receives briefing: "Agent B is editing src/auth/, owns login.ts:validateToken"
  → Agent knows what's in-flight and which conventions apply

User's agent writes a file
  → preToolUse (Write) hook fires
  → Enagrams checks: is this file/symbol reserved? Does any must-tier convention match?
  → If yes: write is denied with context ("Owned by Agent B — 'Build JWT auth'")
  → If no: write proceeds

After successful write
  → postToolUse hook fires
  → Reservation refreshed, symbol graph re-extracted

Conversation ends
  → sessionEnd hook fires
  → All reservations released

​
2. Explicit context (MCP tools)

Agents call 26 MCP tools when they need richer context or want to record something: sync, decide, search, ask, learn, plus workstream, task, convention, negotiation, and test-gate tools.

​
3. Auto-sync (enagrams watch)

Once a change clears the test gate on a workstream branch, enagrams watch on other developers’ machines fetches and applies it automatically. Nobody manually pulls a teammate’s in-progress branch.

​
What an agent knows at session start

A briefing like this is injected automatically: 
Active agents:
  - Developer B's Cursor  [workstream: auth-refactor]
    task: "Build JWT auth flow"
    editing: src/auth/login.ts · symbol: validateToken

Reservations relevant to you:
  - src/auth/login.ts::validateToken  (B, 8 min remaining)
  - src/auth/middleware.ts            (B, 8 min remaining)

Recent decisions (3):
  - "Use JWT for auth" (B, 12 min ago) — stateless, edge-friendly

Applicable conventions:
  - must: "All API routes return { ok, data, error }" (affects src/api/**)
  - should: "Prefer zod over manual validation"

Your task (from claimed work package):
  - Build user registration  (files: src/users/register.ts, src/users/validate.ts)
The agent does not need to ask for this — sessionStart provides it.

​
Conflict detection

Beyond file/symbol locking, sync returns advisory signals:
SignalTypeDescription
Same file/symbol reserved by another sessionConflictHard block via preToolUse
Another agent working in same directoryWarningSoft warning in sync
File recently edited by another agent on a different workstreamWarningSoft warning in sync
Stale decision covering files you’re editingWarningSurfaced via decisions_stale
When a hard block occurs, the affected agent can open a negotiation instead of silently backing off.

​
Session model

Sessions are keyed by conversation_id (Cursor) or session_id (Claude Code/Codex), so:
  • Multiple Cursor tabs → independent sessions, even when sharing one MCP process
  • Sessions auto-expire after 5 minutes of inactivity (no hook events)
  • Sessions appear in the dashboard with agent type, current task, workstream, and touched files/symbols