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)

Try without installing

• 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).

Installation

# 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/

CLI Usage (Easiest Way)

Use the command-line interface for quick operations:

# 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:

# 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

Use Generic Integration (Recommended)

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

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();

Use with Multiple Tools

// 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.

Usage

1. Set shared state:

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

2. Check for conflicts:

coordinator conflicts

3. Inject context before starting agent:

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

Option 1: Auto-inject Hook (Recommended)

coordinator hook install cursor

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

Option 2: Manual Integration

# 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

Option 3: Git Hooks

Add to .git/hooks/post-checkout:

#!/bin/bash
# Use coordinator hook instead
if [ -f .agent-coordinator/hooks/cursor.js ]; then
  node .agent-coordinator/hooks/cursor.js
fi

📊 Real-World Scenarios

Scenario 1: Auth Method Change

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

Without Coordinator:

# 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:

# 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!

Scenario 2: API Version Update

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

Without Coordinator:

# Tool A: Updates API to v2
# Tool B: Still uses v1 endpoints
# Result: ❌ API calls fail, merge conflicts

With Coordinator:

# 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!

Scenario 3: Database Schema Change

Problem: Schema changes not communicated across tools.

Without Coordinator:

# Tool A: Changes user table (adds email field)
# Tool B: Creates queries without email
# Result: ❌ Missing data, broken queries

With Coordinator:

# 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

SimpleCoordinator

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](QUICK_START.md)** - Get started in 5 minutes
- **[CLI Usage](CLI_USAGE.md)** - Complete command reference
- **[How It Works](HOW_IT_WORKS.md)** - Detailed explanation of the system
- **[Product Document](PRODUCT.md)** - Full feature overview
- **[Changelog](CHANGELOG.md)** - Version history and updates

## 🤝 Contributing

Found a bug or have an idea? [Open an issue](https://github.com/mspworld/agent-coordinator/issues) or submit a pull request!

## 📄 License

MIT License - See [LICENSE](LICENSE) file for details.

---

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