Intent Hub

Team-based LLM Coordination Platform with Semantic Conflict Resolution

When multiple developers use AI coding agents simultaneously, code conflicts happen. Intent Hub solves this by coordinating LLM agents at the semantic level - before conflicts occur.

╔═══════════════════════════════════════════════════════════════╗
║   ██╗███╗   ██╗████████╗███████╗███╗   ██╗████████╗           ║
║   ██║████╗  ██║╚══██╔══╝██╔════╝████╗  ██║╚══██╔══╝           ║
║   ██║██╔██╗ ██║   ██║   █████╗  ██╔██╗ ██║   ██║              ║
║   ██║██║╚██╗██║   ██║   ██╔══╝  ██║╚██╗██║   ██║              ║
║   ██║██║ ╚████║   ██║   ███████╗██║ ╚████║   ██║              ║
║   ╚═╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚═╝  ╚═══╝   ╚═╝              ║
║                         HUB                                   ║
╚═══════════════════════════════════════════════════════════════╝

English | 한국어

Table of Contents

• The Problem
• The Solution
• Quick Start
• Installation Guide for LLM Agents
• Team Collaboration Guide
• Integration
• How It Works
• Configuration

The Problem

In modern teams using AI coding assistants (Cursor, GitHub Copilot, OpenCode, etc.):

• Alice asks her AI to "implement OAuth login"
• Bob asks his AI to "add session management"
• Both AIs modify src/auth/* simultaneously
• Result: Merge conflicts, lost work, frustration

Traditional file-level locks don't work because:

1. AI agents don't know about each other
2. Semantic overlap isn't always file-based
3. "auth" and "session" might not touch the same files but are conceptually related

The Solution

Intent Hub introduces Semantic Locks - locking at the domain level (auth, payment, user) rather than file level.

┌─────────────┐     WebSocket      ┌─────────────┐
│  Alice's    │◄──────────────────►│             │
│  AI Agent   │                    │   Intent    │
├─────────────┤                    │    Hub      │
│  Bob's      │◄──────────────────►│   Server    │
│  AI Agent   │                    │             │
├─────────────┤                    │  (Central   │
│  Carol's    │◄──────────────────►│   Coord)    │
│  AI Agent   │                    │             │
└─────────────┘                    └─────────────┘

Key Features

• Smart Intent Analysis: LLM-powered understanding of what each developer intends to do
• Semantic Domain Locking: Lock conceptual areas, not just files
• LLM Negotiation: When conflicts occur, AI agents can negotiate solutions
• Auto-Resolution: Compatible changes proceed automatically
• Human Escalation: Incompatible changes prompt developers for decisions

Quick Start

🚀 Live Share Mode (Recommended for Teams)

Like VS Code Live Share - one person hosts, others join with a link. No network setup needed!

# 1. Install
git clone https://github.com/your-org/intent-hub.git && cd intent-hub
bun install && bun run build

# 2. Start with Live Share mode
bun run packages/hub/dist/cli.js --share --llm=openai

# Output:
# ╔═══════════════════════════════════════════════════════════════╗
# ║                    🔗 SHARE YOUR SESSION                      ║
# ╠═══════════════════════════════════════════════════════════════╣
# ║  Team members can connect using:                              ║
# ║  wss://intent-hub-a1b2c3d4.loca.lt                            ║
# ╚═══════════════════════════════════════════════════════════════╝

# 3. Share the URL with your team!

That's it! Team members connect to the shared URL - no firewall/NAT configuration needed.

Prerequisites

• Bun v1.1.0 or later
• Node.js 20+ (for compatibility)

Installation

git clone https://github.com/your-org/intent-hub.git
cd intent-hub
bun install
bun run build

Start the Hub Server

# 🌐 Live Share mode (for remote teams)
bun run packages/hub/dist/cli.js --share

# 🏠 Local mode (same network only)
bun run packages/hub/dist/cli.js

# With OpenAI
OPENAI_API_KEY=sk-xxx bun run packages/hub/dist/cli.js --share --llm=openai

# With Anthropic
ANTHROPIC_API_KEY=sk-ant-xxx bun run packages/hub/dist/cli.js --llm=anthropic

Server Options

Usage:
  intent-hub [options]

Options:
  --port=<number>           Port to listen on (default: 9876)
  --host=<string>           Host to bind to (default: 0.0.0.0)
  --mode=<mode>             Server mode: simple | smart (default: smart)
  --llm=<provider>          LLM provider: openai | anthropic | mock (default: mock)
  --api-key=<key>           API key for LLM provider (or use env vars)
  --no-negotiate            Disable auto-negotiation
  --dashboard               Enable web dashboard
  --share                   Enable Live Share mode (public URL, no network setup)
  --tunnel=<provider>       Tunnel: auto | localtunnel | cloudflared (default: auto)
  --help                    Show help message

Environment Variables:
  OPENAI_API_KEY       OpenAI API key
  ANTHROPIC_API_KEY    Anthropic API key

Installation Guide for LLM Agents

This section is a reference guide for AI coding agents (Claude Code, OpenCode, Cursor, etc.) when installing Intent Hub.

Quick Install (npx)

Just one command to start a shared session:

# Start Intent Hub with Live Share (recommended)
npx intent-hub --share

# With OpenAI for smart analysis
OPENAI_API_KEY=sk-xxx npx intent-hub --share --llm=openai

That's it! Share the outputted URL with your team.

Step 0: Check Environment with User

Ask the user:

• LLM provider: OpenAI API key? Anthropic API key? Or just test with mock?

Step 1: Start Hub Server

Option A: npx (Recommended - No installation needed):

# Quick start with Live Share
npx intent-hub --share

# With OpenAI
OPENAI_API_KEY=sk-xxx npx intent-hub --share --llm=openai

# With Anthropic
ANTHROPIC_API_KEY=sk-ant-xxx npx intent-hub --share --llm=anthropic

Option B: Global install:

npm install -g intent-hub
intent-hub --share --llm=openai

Option C: From source:

git clone https://github.com/jhmin/intent-hub.git
cd intent-hub && bun install && bun run build
bun run packages/hub/dist/cli.js --share

Step 2: Share the URL

When server starts with --share, it outputs:

╔═══════════════════════════════════════════════════════════════╗
║                    🔗 SHARE YOUR SESSION                      ║
╠═══════════════════════════════════════════════════════════════╣
║  Team members can connect using:                              ║
║  wss://intent-hub-a1b2c3d4.loca.lt                            ║
╚═══════════════════════════════════════════════════════════════╝

Copy and share this URL with your team!

Step 3: Connect Agent Client

Each team member's AI agent connects using:

import { HubClient } from "@jhmin/intent-hub-agent";

const client = new HubClient({
  hubUrl: "wss://intent-hub-a1b2c3d4.loca.lt", // Shared URL
  userId: "unique-user-id",
  username: "Username",
  projectPath: "/path/to/project",
});

client.connect();

Troubleshooting

| Symptom | Cause | Solution | | ----------------- | ------------------ | ------------------------------------------------------------ | | Connection failed | Server not running | Run npx intent-hub --share | | Tunnel error | Network issue | Try --tunnel=cloudflared if you have cloudflared installed | | LLM error | No API key | Set OPENAI_API_KEY or ANTHROPIC_API_KEY env var |

Team Collaboration Guide

Using Intent Hub as a Team

Intent Hub delivers its true value when the entire team uses it together.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                        Team Server                           │
│  ┌────────────────────────────────────────────────────────┐  │
│  │              Intent Hub Server                         │  │
│  │              (ws://team-server:9876)                   │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘
                              ▲
                              │ WebSocket
          ┌───────────────────┼───────────────────┐
          │                   │                   │
          ▼                   ▼                   ▼
    ┌──────────┐       ┌──────────┐       ┌──────────┐
    │ Dev A    │       │ Dev B    │       │ Dev C    │
    │ Claude   │       │ OpenCode │       │ Cursor   │
    │ Code     │       │          │       │          │
    └──────────┘       └──────────┘       └──────────┘

Setup Method

1. Run Hub on Team Server:

# Run in background on team server
nohup bun run packages/hub/dist/cli.js \
  --llm=openai \
  --dashboard \
  --host=0.0.0.0 \
  > intent-hub.log 2>&1 &

2. Configure Each Developer's AI Agent:

Developers can simply ask their AI agent (Claude Code, OpenCode, Cursor, etc.):

"Connect to Intent Hub. The hub server address is ws://team-server:9876, and my name is [username]."

Or add to project config file:

// .intent-hub.json (create in project root)
{
  "hubUrl": "ws://team-server:9876",
  "autoConnect": true
}

How to Request Installation via LLM

Tell your team members:

"Tell your Claude Code / OpenCode / Cursor this:"

"Install Intent Hub client and connect to ws://team-server:9876. My userId is 'my-unique-id' and name is 'John Doe'. GitHub: https://github.com/your-org/intent-hub"

The AI agent will automatically:

1. Install required packages
2. Create config files
3. Connect to hub server
4. Run tests

Collaboration Workflow

┌─────────────────────────────────────────────────────────────────┐
│                    Collaboration Scenario                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Alice: "Implement OAuth login"                              │
│     └─> Intent Hub: Lock acquired for auth/oauth ✓              │
│                                                                 │
│  2. Bob: "Add session management"                               │
│     └─> Intent Hub: Conflict detected in auth domain!           │
│         └─> Notify Bob's AI: "Alice is working on auth.         │
│             Please work on something else or wait."             │
│                                                                 │
│  3. Carol: "Refactor payment system"                            │
│     └─> Intent Hub: Lock acquired for payment ✓                 │
│         (Unrelated to auth, can proceed simultaneously)         │
│                                                                 │
│  4. Alice completes work                                        │
│     └─> Intent Hub: Release auth/oauth lock                     │
│         └─> Notify Bob's AI: "auth is now available"            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Recommended Setup by Team Size

| Team Size | Server Location | LLM Setting | Notes | | --------- | --------------------- | ------------------- | ------------------------ | | 1-3 | Local (one developer) | Mock or OpenAI | Simple setup | | 4-10 | Dedicated team server | OpenAI or Anthropic | Stable connection needed | | 10+ | Cloud (AWS/GCP) | OpenAI + HA | Production-level |

Integration

With OpenCode (Hooks)

import { createIntentHubHooks } from "@intent-hub/agent";

const hooks = createIntentHubHooks({
  hubUrl: "ws://localhost:9876",
  userId: "alice",
  username: "Alice",
  projectPath: "/path/to/project",
  onNotification: (event, data) => {
    console.log(`[IntentHub] ${event}:`, data);
  },
});

// In your AI agent's tool hooks:
// Pre-tool hook - check if action is allowed
const result = await hooks.preToolUse({
  toolName: "edit",
  toolInput: { filePath: "src/auth/login.ts", content: "..." },
  sessionId: "session-123",
  userId: "alice",
  username: "Alice",
});

if (!result.allow) {
  console.log(result.message); // Domain locked by another user
}

// When user submits a prompt
const promptResult = await hooks.onUserPromptSubmit("Add OAuth login with Google");
if (promptResult.message) {
  console.log(promptResult.message); // Warning about locked domains
}

Programmatic Usage

import { HubClient } from "@intent-hub/agent";

const client = new HubClient({
  hubUrl: "ws://localhost:9876",
  userId: "alice",
  username: "Alice",
  projectPath: "/path/to/project",
  onConnected: (sessionId) => {
    console.log("Connected:", sessionId);
  },
  onMessage: (message) => {
    switch (message.type) {
      case "hub:lock:acquired":
        console.log("Lock acquired for domains:", message.payload.domains);
        break;
      case "hub:lock:blocked":
        console.log("Blocked by:", message.payload.blockedBy);
        break;
      case "hub:negotiation:start":
        console.log("Negotiation started with:", message.payload.participants);
        break;
      case "hub:decision:required":
        console.log("Decision needed:", message.payload.question);
        break;
    }
  },
});

client.connect();

// Submit intent when user gives a prompt
client.submitIntent("Implement Google OAuth login");

Architecture

intent-hub/
├── packages/
│   ├── shared/              # Shared types & utilities
│   │   └── src/
│   │       ├── types/       # Intent, Domain, Message types
│   │       └── utils/       # ID generation, message helpers
│   │
│   ├── hub/                 # Central Hub Server
│   │   └── src/
│   │       ├── server/      # WebSocket server
│   │       ├── core/        # Lock manager, conflict detector, orchestrator
│   │       ├── llm/         # LLM provider, analyzer, negotiation engine
│   │       └── state/       # Session management
│   │
│   └── agent/               # Client-side Agent Library
│       └── src/
│           ├── connection/  # Hub client
│           ├── plugin/      # Plugin interface
│           └── hooks/       # OpenCode hooks
│
├── scripts/
│   ├── test-e2e.ts         # End-to-end tests
│   └── test-mvp2.ts        # LLM negotiation tests
│
└── turbo.json              # Turborepo config

How It Works

1. Intent Submission

When a developer gives their AI a task:

User: "Add Google OAuth login"

The agent submits this intent to Intent Hub:

client.submitIntent("Add Google OAuth login");

2. Smart Analysis

Intent Hub analyzes the intent using LLM:

{
  "domain": "auth",
  "subdomain": "oauth",
  "affectedFiles": ["src/auth/oauth.ts", "src/auth/providers/google.ts"],
  "semanticTags": ["login", "oauth", "google", "authentication"],
  "estimatedScope": "medium"
}

3. Conflict Detection

The system checks for semantic conflicts:

| Scenario | Result | | -------------------------------- | -------------------------------------- | | No overlap | Approved - proceed immediately | | Same domain, different subdomain | Warning - may proceed with caution | | Same domain, same subdomain | Blocked or Negotiation |

4. Resolution

Auto-Approved:

Alice: auth/oauth  ✓
Carol: payment     ✓  (different domain)

Blocked:

Alice: auth/oauth  ✓
Bob: auth/session  ⚠️  (same domain - blocked until Alice finishes)

Negotiation (when enabled):

Alice: auth/oauth
Bob: auth/session
→ LLMs discuss and propose: "Alice works on OAuth first, Bob does session after"
→ Both users notified of the plan

Message Protocol

Agent → Hub

| Message | Description | | --------------------- | --------------------------------- | | agent:connect | Initial connection with user info | | agent:intent:submit | Submit a new intent (user prompt) | | agent:decision | User's decision on a conflict |

Hub → Agent

| Message | Description | | -------------------------- | ------------------------------------- | | hub:connected | Connection confirmed with session ID | | hub:intent:received | Intent acknowledged | | hub:intent:analyzed | Analysis complete with domain info | | hub:lock:acquired | Lock granted, proceed with work | | hub:lock:blocked | Lock denied, wait or work elsewhere | | hub:negotiation:start | Negotiation started with another user | | hub:negotiation:resolved | Negotiation complete with plan | | hub:decision:required | User input needed |

Broadcasts

| Message | Description | | ----------------------- | ------------------- | | broadcast:user:joined | New user connected | | broadcast:user:left | User disconnected | | broadcast:lock:update | Lock status changed |

Development

Build

bun install
bun run build

Development Mode

# Watch mode for hub
bun run dev:hub

# Watch mode for agent
bun run dev:agent

Run Tests

# E2E test (basic flow)
bun run scripts/test-e2e.ts

# MVP2 test (LLM negotiation)
bun run scripts/test-mvp2.ts

Type Check

bun run typecheck

Configuration

Hub Server Configuration

interface SmartHubServerOptions {
  port: number; // WebSocket port
  host?: string; // Bind address (default: 0.0.0.0)
  llmProvider: LLMProvider; // OpenAI, Anthropic, or Mock
  orchestratorConfig?: {
    useLLMAnalysis?: boolean; // Use LLM for intent analysis
    autoNegotiate?: boolean; // Auto-negotiate conflicts
    conflictThreshold?: "low" | "medium" | "high";
  };
}

Agent Configuration

interface IntentHubHooksConfig {
  hubUrl: string; // WebSocket URL to hub
  userId: string; // Unique user identifier
  username: string; // Display name
  projectPath: string; // Project root path
  autoConnect?: boolean; // Connect on creation (default: true)
  onNotification?: (event: string, data: unknown) => void;
}

Semantic Domains

Intent Hub automatically categorizes work into semantic domains:

| Domain | Triggers | | ---------- | -------------------------------------------- | | auth | /auth/, login, oauth, session, jwt | | user | /user/, profile, account | | payment | /payment/, checkout, stripe, billing | | api | /api/, route, endpoint | | ui | .tsx, .jsx, /component | | database | /db/, migration, schema | | config | config, .env | | test | .test., .spec., /test/ |

Custom domains can be configured based on your project structure.

Roadmap

• [x] MVP 1: Basic domain locking
• [x] MVP 2: LLM-powered intent analysis & negotiation
• [x] MVP 3: OpenCode integration hooks
• [ ] MVP 4: Web dashboard for team visibility
• [ ] MVP 5: History & analytics
• [ ] MVP 6: VS Code extension

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Built with love by the Intent Hub team. Because AI collaboration should be as smooth as human collaboration (or better).