Skip to main content

​
Architecture Overview

Enagrams has three coordination layers working together:
  1. IDE hooks — automatic, zero-effort coordination at every tool event
  2. MCP tools — 26 tools agents call explicitly for context, decisions, workstreams, tasks, negotiations, and the test gate
  3. Auto-sync engine — enagrams watch propagates gate-approved changes between developers
Agent A (Cursor)                     Agent B (Claude Code)
    │                                     │
    ├── sessionStart ──────┐   ┌───────── SessionStart ─┤
    ├── preToolUse (Write)─┤   ├── PreToolUse (Write) ──┤
    ├── postToolUse (Write)┤   ├── PostToolUse (Write) ─┤
    │                      v   v                        │
    │       ┌────────────────────────────────┐          │
    │       │        Enagrams API            │          │
    │       │                                │          │
    │       │  agent_sessions                │          │
    │       │  file_reservations (symbol-    │          │
    │       │    level via symbol_graph)     │          │
    │       │  decisions  +  conventions     │          │
    │       │  workstreams  +  tasks         │          │
    │       │  negotiations                  │          │
    │       │  symbol_graph_nodes            │          │
    │       │  sync_log  (test gate)         │          │
    │       └────────────────────────────────┘          │
    │                      │                            │
    │              Dashboard (SSE)                      │
    │              enagrams watch (auto-sync)           │

​
Hook-Based Coordination (Always On)

Hooks handle coordination automatically. Your IDE calls them for every relevant event — you never need to think about it.
Hook eventWhen it firesWhat happens
sessionStartNew conversation beginsRegisters an agent_sessions row and injects a team briefing: active agents, locked files/symbols, recent decisions, applicable conventions
preToolUse (Write/Edit)Before any file writeCalls file_lock. If another session owns the file (or any touched symbol), or a must-tier convention matches, the write is denied with a specific message
postToolUse (Write/Edit)After a successful writeRecords the edit, re-extracts the symbol graph for the changed file, and refreshes the reservation
beforeSubmitPromptUser sends a messageCompact team-state refresh — keeps the agent’s context current without a full briefing
sessionEndConversation endsReleases reservations, closes the session
The hook script is a single file (.cursor/hooks/enagrams-hooks.mjs) shared by Cursor, Claude Code, and Codex. It detects the IDE from event-name casing (Cursor uses camelCase, Claude Code and Codex use PascalCase).

​
MCP Tools (Explicit)

Agents reach for MCP tools when they need richer context or want to record something. The 26 tools group into six areas:
AreaTools
Coordination & contextsync, decide, publish, search, ask, learn
Workstreamsworkstream_start, workstream_join, workstream_leave, workstream_end, workstream_complete, workstream_list
Test gateconfirm_ready, sync_commit, sync_retract
Negotiationnegotiate_open, negotiate_respond, negotiate_list
Tasksdelegate_task, task_claim, task_update, task_list
Conventions & living decisionsconvention_propose, convention_list, decisions_stale, decision_reaffirm
See the MCP overview for a full breakdown.

​
File and Symbol Locking

Reservations prevent simultaneous edits, and they work at two levels:
  • File level — for languages we don’t parse or files that changed entirely
  • Symbol level — for TypeScript/JavaScript files, via the symbol graph. Two agents can edit the same file as long as they touch different functions/classes.
Flow:
  1. postToolUse (or file_lock) records the reservation keyed on session, file, and touched symbol IDs.
  2. Reservations expire after 10 minutes of inactivity (sliding window) and are released at sessionEnd.
  3. When another agent tries to write, preToolUse looks up conflicts and denies with a message naming the owner, their task, and the contested symbols.
  4. The blocked agent can open a negotiation to work it out.
The UNIQUE(workspace_id, file_path, symbol_id) constraint prevents race conditions under concurrent load.

​
Workstreams and the Test Gate

A workstream is a named unit of work mapped to a shared Git branch (ena/<slug>). Any change bound for the shared branch flows through the test gate:
  1. Agent touches files/symbols locally.
  2. Agent calls confirm_ready — API returns the minimal set of affected tests derived from the symbol graph.
  3. Agent runs those tests and resubmits the results with test_results.
  4. If all affected tests pass, the API emits a gate_approved event; otherwise it returns gate_blocked with the failing suites.
  5. Agents running enagrams watch auto-merge approved changes on their machines.
Atomic task completion: if confirm_ready is called with completes_task_id, the task is only marked done when the gate approves — no more “I said done but it doesn’t build.”

​
Session Lifecycle

sessionStart hook
  → API creates / re-uses session keyed by conversation_id
  → Returns briefing as additional_context

[conversation in progress]
  → Every hook event refreshes last_heartbeat
  → Sessions auto-expire after 5 min inactivity

sessionEnd hook
  → Releases reservations
  → Ends session
Multiple tabs sharing one MCP process each get independent sessions via their own conversation_id or session_id.

​
Living Decisions and Conventions

Every decide call stores:
  • title, rationale, decision_type, affected files and (when resolvable) symbol IDs
  • embedding — 1536-dim vector for semantic search
  • A link to the symbol graph so the decision can be marked stale when the code it describes changes
Conventions are the enforcement side of the same system: convention_propose records a rule with a tier (must / should / may). must-tier conventions run inside preToolUse and block writes that match their patterns. See Conventions & Living Decisions for details.

​
Real-time Dashboard

https://enagrams.com/dashboard shows:
  • Agent feed — real-time SSE stream of syncs, decisions, file/symbol claims, gate results
  • Workstreams — active branches, members, touched files/symbols, open tasks
  • Decisions — timeline with stale flags
  • Conventions — tier-grouped list
  • Tasks — per-workstream kanban
  • Negotiations — open/resolved turns
  • Knowledge graph — decisions connected by shared symbols

​
Meeting Ingestion

  1. Paste a transcript or record live.
  2. LLM extracts decisions and action items.
  3. A second pass generates non-overlapping work packages scoped to files/symbols.
  4. Team members claim packages.
  5. Claimed packages arrive in sync responses so the assigned agent knows the task, rationale, and exact files to touch.