intent-hub 0.1.0 → 0.1.1

package/.claude/settings.local.json

@@ -1,7 +1,8 @@
 {
   "permissions": {
     "allow": [
-      "mcp__ide__getDiagnostics"
+      "mcp__ide__getDiagnostics",
+      "WebFetch(domain:github.com)"
     ]
   }
 }

package/LICENSE.md

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2026 Jihong Min
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -38,11 +38,12 @@
 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"  
+- **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
@@ -179,11 +180,13 @@ 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):**
+
 ```bash
 # Quick start with Live Share
 npx intent-hub --share
@@ -191,19 +194,21 @@ npx intent-hub --share
 # With OpenAI
 OPENAI_API_KEY=sk-xxx npx intent-hub --share --llm=openai
 
-# With Anthropic  
+# 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/anthropic-for-korea/intent-hub.git
+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
 ```
@@ -211,6 +216,7 @@ bun run packages/hub/dist/cli.js --share
 ### Step 2: Share the URL
 
 When server starts with `--share`, it outputs:
+
 ```
 ╔═══════════════════════════════════════════════════════════════╗
 ║                    🔗 SHARE YOUR SESSION                      ║
@@ -227,13 +233,13 @@ Copy and share this URL with your team!
 Each team member's AI agent connects using:
 
 ```typescript
-import { HubClient } from '@anthropic-for-korea/intent-hub-agent';
+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',
+  hubUrl: "wss://intent-hub-a1b2c3d4.loca.lt", // Shared URL
+  userId: "unique-user-id",
+  username: "Username",
+  projectPath: "/path/to/project",
 });
 
 client.connect();
@@ -241,11 +247,11 @@ 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 |
+| 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          |
 
 ---
 
@@ -311,12 +317,13 @@ Or add to project config file:
 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
@@ -350,11 +357,11 @@ The AI agent will automatically:
 
 #### 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 |
+| 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         |
 
 ---
 
@@ -363,13 +370,13 @@ The AI agent will automatically:
 ### With OpenCode (Hooks)
 
 ```typescript
-import { createIntentHubHooks } from '@intent-hub/agent';
+import { createIntentHubHooks } from "@intent-hub/agent";
 
 const hooks = createIntentHubHooks({
-  hubUrl: 'ws://localhost:9876',
-  userId: 'alice',
-  username: 'Alice',
-  projectPath: '/path/to/project',
+  hubUrl: "ws://localhost:9876",
+  userId: "alice",
+  username: "Alice",
+  projectPath: "/path/to/project",
   onNotification: (event, data) => {
     console.log(`[IntentHub] ${event}:`, data);
   },
@@ -378,11 +385,11 @@ const hooks = createIntentHubHooks({
 // 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',
+  toolName: "edit",
+  toolInput: { filePath: "src/auth/login.ts", content: "..." },
+  sessionId: "session-123",
+  userId: "alice",
+  username: "Alice",
 });
 
 if (!result.allow) {
@@ -390,7 +397,7 @@ if (!result.allow) {
 }
 
 // When user submits a prompt
-const promptResult = await hooks.onUserPromptSubmit('Add OAuth login with Google');
+const promptResult = await hooks.onUserPromptSubmit("Add OAuth login with Google");
 if (promptResult.message) {
   console.log(promptResult.message); // Warning about locked domains
 }
@@ -399,29 +406,29 @@ if (promptResult.message) {
 ### Programmatic Usage
 
 ```typescript
-import { HubClient } from '@intent-hub/agent';
+import { HubClient } from "@intent-hub/agent";
 
 const client = new HubClient({
-  hubUrl: 'ws://localhost:9876',
-  userId: 'alice',
-  username: 'Alice',
-  projectPath: '/path/to/project',
+  hubUrl: "ws://localhost:9876",
+  userId: "alice",
+  username: "Alice",
+  projectPath: "/path/to/project",
   onConnected: (sessionId) => {
-    console.log('Connected:', sessionId);
+    console.log("Connected:", sessionId);
   },
   onMessage: (message) => {
     switch (message.type) {
-      case 'hub:lock:acquired':
-        console.log('Lock acquired for domains:', message.payload.domains);
+      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);
+      case "hub:lock:blocked":
+        console.log("Blocked by:", message.payload.blockedBy);
         break;
-      case 'hub:negotiation:start':
-        console.log('Negotiation started with:', message.payload.participants);
+      case "hub:negotiation:start":
+        console.log("Negotiation started with:", message.payload.participants);
         break;
-      case 'hub:decision:required':
-        console.log('Decision needed:', message.payload.question);
+      case "hub:decision:required":
+        console.log("Decision needed:", message.payload.question);
         break;
     }
   },
@@ -430,7 +437,7 @@ const client = new HubClient({
 client.connect();
 
 // Submit intent when user gives a prompt
-client.submitIntent('Implement Google OAuth login');
+client.submitIntent("Implement Google OAuth login");
 ```
 
 ## Architecture
@@ -468,18 +475,21 @@ intent-hub/
 ### 1. Intent Submission
 
 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');
+client.submitIntent("Add Google OAuth login");
 ```
 
 ### 2. Smart Analysis
 
 Intent Hub analyzes the intent using LLM:
+
 ```json
 {
   "domain": "auth",
@@ -494,27 +504,30 @@ Intent Hub analyzes the intent using LLM:
 
 The system checks for semantic conflicts:
 
-| Scenario | Result |
-|----------|--------|
-| No overlap | **Approved** - proceed immediately |
+| Scenario                         | Result                                 |
+| -------------------------------- | -------------------------------------- |
+| No overlap                       | **Approved** - proceed immediately     |
 | Same domain, different subdomain | **Warning** - may proceed with caution |
-| Same domain, same subdomain | **Blocked** or **Negotiation** |
+| 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
@@ -526,31 +539,31 @@ Bob: auth/session
 
 ### Agent → Hub
 
-| Message | Description |
-|---------|-------------|
-| `agent:connect` | Initial connection with user info |
+| 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 |
+| `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 |
+| 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 |
+| Message                 | Description         |
+| ----------------------- | ------------------- |
+| `broadcast:user:joined` | New user connected  |
+| `broadcast:user:left`   | User disconnected   |
 | `broadcast:lock:update` | Lock status changed |
 
 ## Development
@@ -594,13 +607,13 @@ bun run typecheck
 
 ```typescript
 interface SmartHubServerOptions {
-  port: number;                    // WebSocket port
-  host?: string;                   // Bind address (default: 0.0.0.0)
-  llmProvider: LLMProvider;        // OpenAI, Anthropic, or Mock
+  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';
+    useLLMAnalysis?: boolean; // Use LLM for intent analysis
+    autoNegotiate?: boolean; // Auto-negotiate conflicts
+    conflictThreshold?: "low" | "medium" | "high";
   };
 }
 ```
@@ -609,11 +622,11 @@ interface SmartHubServerOptions {
 
 ```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)
+  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;
 }
 ```
@@ -622,16 +635,16 @@ interface IntentHubHooksConfig {
 
 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/` |
+| 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.