How It Works

Architecture Overview

Enagrams has three coordination layers working together:

IDE hooks — automatic, zero-effort coordination at every tool event
MCP tools — 26 tools agents call explicitly for context, decisions, workstreams, tasks, negotiations, and the test gate
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 event	When it fires	What happens
`sessionStart`	New conversation begins	Registers an `agent_sessions` row and injects a team briefing: active agents, locked files/symbols, recent decisions, applicable conventions
`preToolUse` (Write/Edit)	Before any file write	Calls `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 write	Records the edit, re-extracts the symbol graph for the changed file, and refreshes the reservation
`beforeSubmitPrompt`	User sends a message	Compact team-state refresh — keeps the agent’s context current without a full briefing
`sessionEnd`	Conversation ends	Releases 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:

Area	Tools
Coordination & context	`sync`, `decide`, `publish`, `search`, `ask`, `learn`
Workstreams	`workstream_start`, `workstream_join`, `workstream_leave`, `workstream_end`, `workstream_complete`, `workstream_list`
Test gate	`confirm_ready`, `sync_commit`, `sync_retract`
Negotiation	`negotiate_open`, `negotiate_respond`, `negotiate_list`
Tasks	`delegate_task`, `task_claim`, `task_update`, `task_list`
Conventions & living decisions	`convention_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:

postToolUse (or file_lock) records the reservation keyed on session, file, and touched symbol IDs.
Reservations expire after 10 minutes of inactivity (sliding window) and are released at sessionEnd.
When another agent tries to write, preToolUse looks up conflicts and denies with a message naming the owner, their task, and the contested symbols.
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:

Agent touches files/symbols locally.
Agent calls confirm_ready — API returns the minimal set of affected tests derived from the symbol graph.
Agent runs those tests and resubmits the results with test_results.
If all affected tests pass, the API emits a gate_approved event; otherwise it returns gate_blocked with the failing suites.
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

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

Getting Started

Setup Guides

Concepts

Architecture Overview

Hook-Based Coordination (Always On)

MCP Tools (Explicit)

File and Symbol Locking

Workstreams and the Test Gate

Session Lifecycle

Living Decisions and Conventions

Real-time Dashboard

Meeting Ingestion

​Architecture Overview

​Hook-Based Coordination (Always On)

​MCP Tools (Explicit)

​File and Symbol Locking

​Workstreams and the Test Gate

​Session Lifecycle

​Living Decisions and Conventions

​Real-time Dashboard

​Meeting Ingestion

Architecture Overview

Hook-Based Coordination (Always On)

MCP Tools (Explicit)

File and Symbol Locking

Workstreams and the Test Gate

Session Lifecycle

Living Decisions and Conventions

Real-time Dashboard

Meeting Ingestion