Agent Coordinator


v1.9.0 — First public release (January 28, 2026)

The missing shared brain for Cursor, Claude Code, Antigravity, Gemini CLI, and every other AI coding tool you use.

Universal cross-tool coordination for AI coding tools. Preserves context and prevents conflicts when switching between Cursor, Antigravity, GitHub Copilot, and other AI coding tools on the same project.

Positioning: "Mem0 for files, without the server" — file-based, tool-agnostic coordination with zero setup. No Docker, no servers, no accounts. Just JSON files in .agent-coordinator/.

Docs: Quick Start · CLI Usage · How It Works · Product Document · Changelog

🎯 Problem

When you switch between AI coding tools (Cursor → Antigravity) on the same project, context is lost:

- You work in Cursor → Chat history, context, decisions stored in Cursor
- You switch to Antigravity → Antigravity has NO IDEA what Cursor did
- Antigravity starts from scratch → Reads code, doesn't know your decisions
- Result: Lost context, repeated work, conflicts

Example:
- Cursor: Changes auth from JWT to Sessions
- Antigravity: Builds UI expecting JWT (doesn't know about Sessions)
- Result: UI broken, conflicts, wasted work

✅ Solution

Agent Coordinator provides a universal coordination layer:

1. Shared State - Tools declare state changes (e.g., AUTH_METHOD=Sessions)
2. Context Preservation - Preserves context when switching tools
3. Conflict Detection - Detects when tools make conflicting decisions
4. Context Injection - Injects shared state into agent prompts

How it works:
- Tools read/write JSON files in .agent-coordinator/ directory
- Cursor declares: AUTH_METHOD = Sessions
- Antigravity reads: Sees AUTH_METHOD = Sessions, builds UI for Sessions
- Result: Context preserved, no conflicts

🆚 How It Compares to Existing Tools

Positioning: "Mem0 for files, without the server" — file-based, tool-agnostic coordination with zero setup.

| Solution | Setup | Tool Support | Our Advantage |
|----------|-------|--------------|---------------|
| OpenMemory/Mem0 (46K+ stars) | Local MCP server + config | MCP only | ✅ No server process, file-based |
| Swarm Tools | Ecosystem/workflow adoption | Framework-bound | ✅ Simpler surface area, file-based |
| Agentfield | Infrastructure stack | Infrastructure-bound | ✅ Drop-in coordinator, repo-local |
| Cursor Parallel Agents | Official feature | Cursor only | ✅ Tool-agnostic, explicit state |
| Claude Code Memory | Official feature | Claude only | ✅ Tool-agnostic, conflict detection |
| ULPI | Account/platform | Platform-bound | ✅ No account, repo-local |
| Orchestre | Tool-specific | Claude only | ✅ Tool-agnostic (any tool) |
| Pochi/Cursor | Product-specific | Cursor only | ✅ Tool-agnostic (any tool) |

Unique strengths:
- ✅ Repo-local, file-only — No server process (even local), no infrastructure stack, no accounts, no platforms (just JSON files)
- ✅ Tool-agnostic — Works with Cursor, Claude Code, Gemini CLI, Copilot, any tool (not locked to one vendor)
- ✅ Code-specific — Git awareness, conflict detection, task dependencies (not generic memory)
- ✅ Standardized format + CLI — Not just a capability, but a coordination format with conflict detection
- ✅ Zero setup — Just read/write .agent-coordinator/ files (no ecosystem adoption required)

See EXISTING_TOOLS_CHECK.md for full competitive analysis.

🚀 Quick Start (Works with ANY Tool)

$3

- GitHub Codespaces: Open this repo in Codespaces; Node.js is pre-installed. Run node cli.js help from the repo root.
- Replit / other: Clone the repo, then node cli.js help. No npm install required (zero dependencies).

$3

``bash


Option 1: Install globally (recommended)

npm install -g agent-coordinator

Option 2: Use locally in your project

npm install agent-coordinator

Option 3: Copy files directly

cp agent-coordinator/coordinator-simple.js your-project/
cp agent-coordinator/integrations/generic-integration.js your-project/
`

$3

Use the command-line interface for quick operations:

`bash


Set state

coordinator state set AUTH_METHOD JWT Sessions --reason "Better security"

Get state

coordinator state get AUTH_METHOD

Check for conflicts

coordinator conflicts

Show status

coordinator status

Watch for changes in real-time

coordinator watch

List decisions

coordinator decisions

Inject context for current tool

coordinator context inject

Get help

coordinator help
`

Example workflow:
`bash


Tool 1 (Cursor) - Set state

coordinator state set AUTH_METHOD JWT Sessions --tool cursor --reason "Better security"

Tool 2 (Antigravity) - Check state before starting

coordinator state get AUTH_METHOD

Output: Sessions (set by cursor)

Check for conflicts

coordinator conflicts

Watch for changes

coordinator watch
`

$3

Works with ANY tool - Cursor, Antigravity, Copilot, Aider, or your custom tool:

`javascript
import { GenericToolIntegration } from './generic-integration.js';

// Auto-detects tool or specify explicitly
const integration = new GenericToolIntegration(); // Auto-detect
// or
const integration = new GenericToolIntegration('my-tool'); // Explicit

// Before agent starts - get context from other tools
const context = await integration.generateContextString();
// Inject into your tool's agent prompt

// When agent makes decision
await integration.recordDecision(
'AUTH_METHOD',
'JWT',
'Sessions',
{ reason: 'Better security' }
);

// Check for conflicts
const { hasConflicts } = await integration.checkConflicts();
`

$3

`javascript
// Tool 1 (any tool)
const tool1 = new GenericToolIntegration('tool-1');
await tool1.recordDecision('AUTH_METHOD', 'JWT', 'Sessions');

// Tool 2 (any tool) - sees Tool 1's decision
const tool2 = new GenericToolIntegration('tool-2');
const state = await tool2.getState('AUTH_METHOD');
// Sees: { value: 'Sessions', set_by: 'tool-1' }
`

See integrations/universal-integration.md for complete guide.

$3

#### 1. Set shared state:

`bash
coordinator state set AUTH_METHOD JWT Sessions --reason "Better security"
`

#### 2. Check for conflicts:

`bash
coordinator conflicts
`

#### 3. Inject context before starting agent:

`bash
coordinator context inject cursor
`

📁 Project Structure

`
agent-coordinator/
├── coordinator-simple.js # Core coordination logic (main entry)
├── cli.js # Command-line interface
├── integrations/ # Tool-specific integrations
│ ├── generic-integration.js
│ ├── cursor-integration.js
│ ├── claude-code-integration.js
│ └── ...
├── examples/ # Usage examples
├── test-simple.js # Test suite
└── .agent-coordinator/ # Runtime state (created at runtime)
├── state.json
├── decisions.jsonl
└── tasks.json
`

🔧 Integration with Cursor

$3

`bash
coordinator hook install cursor
`

This creates .agent-coordinator/hooks/cursor.js and a Cursor rule that reminds you to run it before starting agents.

$3

`bash


Before starting an agent in Cursor


coordinator context inject cursor
`

Create a Cursor extension that:
- Hooks into worktree creation
- Automatically calls onAgentStart()
- Injects context into agent prompts

$3

Add to .git/hooks/post-checkout:

`bash
#!/bin/bash


Use coordinator hook instead


if [ -f .agent-coordinator/hooks/cursor.js ]; then
node .agent-coordinator/hooks/cursor.js
fi
`

📊 Real-World Scenarios

$3

Problem: You switch tools mid-project and lose context.

Without Coordinator:
`bash


In Cursor: Change auth from JWT to Sessions

You update backend code, but forget to tell other tools

Switch to Antigravity: Builds login UI

Antigravity doesn't know about Sessions change

Result: UI uses JWT, backend uses Sessions → ❌ Broken!

`

With Coordinator:
`bash


In Cursor: Change auth and declare it

coordinator state set AUTH_METHOD JWT Sessions --tool cursor --reason "Better security"

Switch to Antigravity: Check state first

coordinator state get AUTH_METHOD

Output: Sessions (set by cursor)

Antigravity builds UI for Sessions → ✅ Works perfectly!

`

$3

Problem: Multiple tools working on same API, version conflicts.

Without Coordinator:
`bash


Tool A: Updates API to v2

Tool B: Still uses v1 endpoints

Result: ❌ API calls fail, merge conflicts

`

With Coordinator:
`bash


Tool A: Update API version

coordinator state set API_VERSION v1 v2 --tool cursor --reason "Breaking changes"

Tool B: Check version before making changes

coordinator state get API_VERSION

Output: v2 (set by cursor)

Tool B uses v2 endpoints → ✅ Everything aligned!

`

$3

Problem: Schema changes not communicated across tools.

Without Coordinator:
`bash


Tool A: Changes user table (adds email field)

Tool B: Creates queries without email

Result: ❌ Missing data, broken queries

`

With Coordinator:
`bash


Tool A: Declare schema change

coordinator state set USER_SCHEMA "id,name" "id,name,email" --tool claude-code --reason "Add email field"

Tool B: Check schema before querying

coordinator state get USER_SCHEMA

Output: id,name,email (set by claude-code)

Tool B includes email in queries → ✅ All queries work!

`

📝 API Reference

$3

`javascript
import SimpleCoordinator from './coordinator-simple.js';

const coordinator = new SimpleCoordinator();

// Declare state change
await coordinator.declareStateChange('AUTH_METHOD', 'JWT', 'Sessions', {
tool: 'cursor',
reason: 'Better security'
});

// Get state
const state = coordinator.getState('AUTH_METHOD');

// Check conflicts
const conflicts = coordinator.checkConflicts();

// Generate context string
const context = coordinator.generateContextString('claude-code');
`
// See examples/ for more usage patterns
``

📚 More Documentation

- Quick Start Guide - Get started in 5 minutes
- CLI Usage - Complete command reference
- How It Works - Detailed explanation of the system
- Product Document - Full feature overview
- Changelog - Version history and updates

🤝 Contributing

Found a bug or have an idea? Open an issue or submit a pull request!

📄 License

MIT License - See LICENSE file for details.

---

Made with ❤️ for developers who use multiple AI coding tools