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 │ │ │
└─────────────┘ └─────────────┘
`

$3

- 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

$3

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

`bash


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.

---

$3

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

$3

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

$3

`bash


🌐 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
`

$3

`
Usage:
intent-hub [options]

Options:
--port= Port to listen on (default: 9876)
--host= Host to bind to (default: 0.0.0.0)
--mode= Server mode: simple | smart (default: smart)
--llm= LLM provider: openai | anthropic | mock (default: mock)
--api-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= 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.

$3

Just one command to start a shared session:

`bash


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.

---

$3

Ask the user:

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

$3

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

`bash


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:

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

Option C: From source:

`bash
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
`

$3

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!

$3

Each team member's AI agent connects using:

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

$3

| 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

$3

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:

`bash


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:

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

$3

`typescript
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
}
`

$3

`typescript
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

$3

When a developer gives their AI a task:

`
User: "Add Google OAuth login"
`

The agent submits this intent to Intent Hub:

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

$3

Intent Hub analyzes the intent using LLM:

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

$3

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 |

$3

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

$3

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

$3

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

$3

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

Development

$3

`bash
bun install
bun run build
`

$3

`bash


Watch mode for hub

bun run dev:hub

Watch mode for agent

bun run dev:agent
`

$3

`bash


E2E test (basic flow)

bun run scripts/test-e2e.ts

MVP2 test (LLM negotiation)

bun run scripts/test-mvp2.ts
`

$3

`bash
bun run typecheck
`

Configuration

$3

`typescript
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";
};
}
`

$3

`typescript
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).