> ## Documentation Index > Fetch the complete documentation index at: https://docs.enagrams.com/llms.txt > Use this file to discover all available pages before exploring further. # How It Works > The coordination model behind Enagrams ## 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 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](/concepts/conventions) matches, the write is denied with a specific message | | `postToolUse` (Write/Edit) | After a successful write | Records the edit, re-extracts the [symbol graph](/concepts/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`](/mcp/sync), [`decide`](/mcp/decide), [`publish`](/mcp/publish), [`search`](/mcp/search), [`ask`](/mcp/ask), [`learn`](/mcp/learn) | | Workstreams | [`workstream_start`](/mcp/workstream-start), [`workstream_join`](/mcp/workstream-join), [`workstream_leave`](/mcp/workstream-leave), [`workstream_end`](/mcp/workstream-end), [`workstream_complete`](/mcp/workstream-complete), [`workstream_list`](/mcp/workstream-list) | | Test gate | [`confirm_ready`](/mcp/confirm-ready), [`sync_commit`](/mcp/sync-commit), [`sync_retract`](/mcp/sync-retract) | | Negotiation | [`negotiate_open`](/mcp/negotiate-open), [`negotiate_respond`](/mcp/negotiate-respond), [`negotiate_list`](/mcp/negotiate-list) | | Tasks | [`delegate_task`](/mcp/delegate-task), [`task_claim`](/mcp/task-claim), [`task_update`](/mcp/task-update), [`task_list`](/mcp/task-list) | | Conventions & living decisions | [`convention_propose`](/mcp/convention-propose), [`convention_list`](/mcp/convention-list), [`decisions_stale`](/mcp/decisions-stale), [`decision_reaffirm`](/mcp/decision-reaffirm) | See the [MCP overview](/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](/concepts/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](/concepts/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](/concepts/workstreams) is a named unit of work mapped to a shared Git branch (`ena/`). Any change bound for the shared branch flows through the [test gate](/concepts/test-gate): 1. Agent touches files/symbols locally. 2. Agent calls [`confirm_ready`](/mcp/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`](/mcp/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](/concepts/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`](/mcp/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](/concepts/conventions) 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.