Team-based LLM coordination platform with semantic conflict resolution
npm install intent-hubTeam-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 ║
╚═══════════════════════════════════════════════════════════════╝
---
- The Problem
- The Solution
- Quick Start
- Installation Guide for LLM Agents
- Team Collaboration Guide
- Integration
- How It Works
- Configuration
---
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
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 │ │ │
└─────────────┘ └─────────────┘
- 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
Like VS Code Live Share - one person hosts, others join with a link. No network setup needed!
`bash1. Install
git clone https://github.com/your-org/intent-hub.git && cd intent-hub
bun install && bun run build
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.jsWith OpenAI
OPENAI_API_KEY=sk-xxx bun run packages/hub/dist/cli.js --share --llm=openaiWith 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 --shareWith 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 --shareWith OpenAI
OPENAI_API_KEY=sk-xxx npx intent-hub --share --llm=openaiWith 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:hubWatch mode for agent
bun run dev:agent
`$3
`bash
E2E test (basic flow)
bun run scripts/test-e2e.tsMVP2 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`)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).