Skip to main content

​
Prerequisites

  • Node.js 18+
  • An AI coding IDE (Cursor, Claude Code, Codex, or any client with Model Context Protocol support)

​
Install

From the root of the repository you want to coordinate: 
npx enagrams init
That single command:
  1. Opens your browser for authentication — no manual API keys to copy
  2. Creates the workspace (or joins yours if one exists for this slug)
  3. Writes the global API key to ~/.config/enagrams/config.json
  4. Writes the workspace slug to .env (ENAGRAMS_WORKSPACE=...)
  5. Drops IDE configs for Cursor (.cursor/hooks.json, .cursor/mcp.json), Claude Code (.mcp.json, .claude/settings.json), and Codex (.codex/hooks.json)
  6. Installs the hook script at .cursor/hooks/enagrams-hooks.mjs
  7. Offers to install enagrams globally so you can drop npx
Reopen your IDE after init so the MCP server and hooks are picked up.
The first init on a new machine triggers a browser-based device code flow. Subsequent inits in other repos reuse your saved API key automatically.

​
Verify

enagrams status
You should see your workspace name and — once your IDE is open — an active agent session.

​
Join an Existing Workspace

If a teammate already created the workspace: 
npx enagrams join
Pick the workspace from the list. The same config files are written for the current repo.

​
What’s Installed

FilePurpose
~/.config/enagrams/config.jsonAPI key (global, like gh / vercel)
.envENAGRAMS_WORKSPACE=<slug> for this repo
.cursor/mcp.jsonMCP server config for Cursor
.cursor/hooks.json + .cursor/hooks/enagrams-hooks.mjsCursor event hooks
.mcp.jsonMCP server config for Claude Code
.claude/settings.jsonClaude Code hook config (reuses the Cursor hook script)
.codex/hooks.jsonCodex hook config
All configs point to the same hook script, so every agent in every IDE on your machine emits activity to the same workspace.

​
Your First Coordinated Edit

1

Open your IDE

Cursor, Claude Code, or Codex. The sessionStart hook fires, your session is registered, and you’ll see a team briefing in the hook output.
2

Have your agent read and edit a file

On the first write, the preToolUse hook calls file_lock so you own that file until your session ends or your agent runs session_end.
3

Ask a teammate to edit the same file

Their agent’s preToolUse hook is denied with a message telling them who owns it and what you’re working on. They route around.
4

Make an architectural choice

Call the decide MCP tool from your agent. Every teammate’s next sync surfaces the decision immediately.

​
Next Steps

How Enagrams works

The coordination model from hooks to sync.

All 24 MCP tools

Every tool your agents can call.

IDE setup guides

Cursor, Claude Code, and Codex specifics.

CLI reference

Every enagrams command.