🌉 IntentBridge

AI-Powered Requirement Management for Claude Code

Features • Quick Start • Documentation • Examples • Contributing

📖 Overview

IntentBridge is an intelligent requirement management tool designed specifically for Claude Code. It bridges the gap between human requirements and AI understanding through progressive context building and AI-powered analysis.

Why IntentBridge?

🧠 Persistent Memory - Requirements never lost, Claude always remembers
📈 Progressive Understanding - From raw description to code implementation (L0→L4)
🤖 AI-Driven Analysis - Auto-generate understanding, impact analysis, validation
🌍 Multi-Project Management - Manage all projects from one place
🔗 MCP Integration - Seamless integration with Claude Code via Model Context Protocol
🎯 Natural Language Interface - Just describe what you want in plain language

✨ Features

🎯 Core Capabilities

Feature	Description
Requirement Management	Full CRUD operations, tags, acceptance criteria, dependencies
AI-Powered Understanding	Generate deep understanding, impact analysis, completion validation
Multi-Project Support	Register, switch, link, and share files across projects
Multi-Project Coordination	v3.4.0: Port management, process monitoring, resource coordination
Smart Commands	NEW v3.6.0: Natural language, short aliases, auto-completion
Error System	NEW v3.6.0: 58 error codes, multilingual support, friendly messages
Performance Monitoring	NEW v3.6.0: Execution time, memory usage, performance reports
Intelligent Cache	NEW v3.6.0: Multi-layer cache, auto-invalidation, LRU eviction
Progressive Context	L0 (Raw) → L1 (Standardized) → L2 (Structured) → L3 (AI-Enhanced) → L4 (Code-Anchored)
MCP Bridge	Export context for Claude Code, session management
Natural Language Router	`ib do "add user auth requirement"` - just describe what you want
Smart Project Creation	AI analyzes requirements and auto-creates project structure

🚀 Key Innovations

Auto Project Detection - Detects project context automatically based on directory
Natural Language Commands - No need to memorize complex CLI syntax
AI Project Scaffolding - One command creates complete project structure with docs
MCP Protocol - Real bidirectional communication with Claude Code
Multi-Project Coordination - Manage ports, processes, and resources across multiple projects
Smart Command System - NEW v3.6.0: Natural language + short aliases + auto-completion
Intelligent Error System - NEW v3.6.0: 58 error codes with multilingual support
Performance & Cache - NEW v3.6.0: Built-in monitoring and intelligent caching

📦 Installation

One-Line Install (Recommended)

The fastest way to get started with IntentBridge:

curl -fsSL https://raw.githubusercontent.com/404QAQ/intentbridge/main/install.sh | bash

What the installer does:

✅ Checks and installs Node.js (v18+) if needed
✅ Installs IntentBridge globally
✅ Checks for Claude Code CLI (optional)
✅ Configures Claude API key
✅ Configures IntentBridge AI provider
✅ Initializes your first project
✅ Optionally starts the Web UI dashboard

Manual installation (if you prefer):

npm install -g intentbridge

Prerequisites

Node.js >= 18.0.0
npm or yarn

Verify Installation

ib --version
# Output: 3.4.0

🎮 Quick Start

1. Initialize a Project

mkdir my-project && cd my-project
ib init

2. Add Your First Requirement

Option A: Interactive Mode

ib req add
> Title: User Authentication
> Description: Implement JWT-based login
> Priority: high
✔ Created REQ-001

Option B: Natural Language

ib do "添加用户认证需求"

Option C: AI-Powered (Recommended)

ib smart-add "需要一个用户认证系统，支持 JWT 和 OAuth2.0"

AI will:

Analyze requirement
Create project structure (src/, tests/, docs/)
Generate README.md, package.json, tsconfig.json
Add requirement to IntentBridge

3. View Requirements

ib req list
ib explain REQ-001          # Compact view for Claude Code
ib show-understanding REQ-001  # Detailed document

4. Work with Claude Code

# Export context for Claude Code
ib mcp export REQ-001

# Copy and paste into Claude Code conversation

5. Validate Completion

ib ai validate REQ-001 --with-code

6. Visualize with Web UI (NEW! 🎉)

IntentBridge now includes a beautiful web-based dashboard for managing requirements:

# Start the web dashboard
ib web start

# Opens:
# - Dashboard: http://localhost:3000
# - API Server: http://localhost:9528

Web UI Features:

🌙 Dark Mode - Automatic detection + manual toggle
🔄 Real-Time Updates - Auto-refresh every 10 seconds
🔍 Advanced Filtering - Search, status, priority, tags
📤 Export Options - CSV, JSON, Markdown formats

Quick Tour:

┌──────────────────────────────────────────────────┐
│  Dashboard                    🌙 Toggle Theme   │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐          │
│  │ 12   │ │  5   │ │ 48   │ │ 75%  │          │
│  │Projs │ │Active│ │ Reqs │ │ Done │          │
│  └──────┘ └──────┘ └──────┘ └──────┘          │
│                                                  │
│  [Requirements] → Filter, Search, Export       │
│  Click any requirement → View full details     │
└──────────────────────────────────────────────────┘

See Web UI Documentation for detailed usage and screenshots.

7. Multi-Project Coordination (NEW! v3.4.0 🚀)

IntentBridge v3.4.0 introduces comprehensive multi-project coordination capabilities:

Port Management:

# Check for port conflicts across all projects
ib project ports check

# Find available ports automatically
ib project ports find --range 3000-4000 --count 3

# Assign ports to projects
ib project ports assign my-project 8080

Process Monitoring:

# Start a project with monitoring
ib project start my-project --auto-ports

# View all running processes
ib project ps

# Check resource usage
ib project resources my-project

Real-time Dashboard:

# View unified dashboard of all projects
ib project dashboard

# Shows:
# - Running projects and their PIDs
# - Port usage and conflicts
# - CPU/Memory consumption
# - Dependency graph

Key Features:

🔄 Automatic Port Allocation - Find and assign ports automatically
📊 Resource Monitoring - Track CPU/memory usage per project
🔗 Dependency Orchestration - Start/stop projects in correct order
🎯 Conflict Prevention - Detect and prevent port conflicts
📈 Real-time Dashboard - Unified view of all projects

See Multi-Project Coordination Guide for complete documentation.

📚 Documentation

🚀 Quick Start & Help

New to IntentBridge? Start here:

📖 5-Minute Quick Start - Get up and running in 5 minutes
🔧 Troubleshooting Guide - Solutions to common problems
❌ Error Codes Reference - Complete error code documentation
🎯 Optimization Plan - Roadmap for improvements

📚 Practical Tutorials (NEW! v3.5.0)

Hands-on learning with real projects:

📝 Tutorial 1: Personal Blog System - 30 min, beginner (⭐⭐☆☆☆)
🛒 Tutorial 2: E-commerce Backend - 45 min, intermediate (⭐⭐⭐☆☆)
🏗️ Tutorial 3: Microservices Architecture - 60 min, advanced (⭐⭐⭐⭐☆)
📋 All Tutorials - Complete tutorial index

💡 Smart Commands (NEW! v3.5.0)

IntentBridge now supports natural language and short commands:

# Natural language
ib "添加用户登录功能"
ib "查看所有需求"
ib "完成 REQ-001"

# Short commands
ib add "登录功能"      # ib req add
ib ls                   # ib req list
ib done REQ-001        # ib req update --status done
ib start my-project    # ib project start
ib web                 # ib web start

📦 Installation

See Installation Section or run:

curl -fsSL https://raw.githubusercontent.com/404QAQ/intentbridge/main/install.sh | bash

Core Commands

Requirement Management

# Add requirement
ib req add
ib req add --template user-auth

# List requirements
ib req list
ib req search "authentication"

# Update requirement
ib req update REQ-001 --status implementing
ib req done REQ-001

# Acceptance criteria
ib req ac REQ-001 "User can login"
ib req accept REQ-001 0

# Dependencies
ib req dep REQ-002 REQ-001  # REQ-002 depends on REQ-001

File Mapping

ib map add REQ-001 src/auth.ts src/middleware/auth.ts
ib map list
ib which src/auth.ts  # Find related requirements

Milestones

ib milestone create "v1.0 Release" "2024-12-31"
ib milestone add "v1.0 Release" REQ-001
ib milestone list

AI Features

# Configure AI (first time)
ib ai config

# Generate AI understanding
ib ai understand REQ-001

# Analyze impact
ib analyze-impact REQ-001

# Validate completion
ib ai validate REQ-001 --with-code

Multi-Project Management

# Register projects
ib project register --name "frontend" --tags "react"
ib project register --name "backend" --tags "nodejs"

# List projects
ib project list

# Switch projects
ib project switch backend

# Global views
ib global-status        # All projects overview
ib global-reqs         # All requirements across projects
ib global-reqs --tag frontend

Natural Language Interface

ib do "在 project-a 添加用户认证需求"
ib do "查看 project-b 的进度"
ib do "更新 REQ-001 状态为 done"
ib do "搜索认证相关需求"

Smart Analysis

ib smart-add "需要一个电商网站，支持商品浏览、购物车、订单管理"
# AI creates:
# - Project structure (src/, tests/, docs/)
# - Configuration files (package.json, tsconfig.json)
# - README.md
# - Requirement REQ-XXX

MCP Integration

# Start MCP server
ib mcp-server start --port 9527

# View status
ib mcp-server status

# List available tools
ib mcp-server tools

# Export context (manual)
ib mcp export REQ-001

Auto Detection

# Detect current project
ib detect

# Works from any subdirectory
cd src/components
ib detect  # Still recognizes the project

💡 Examples

Example 1: New Project from Scratch

# 1. Create and initialize
mkdir saas-app && cd saas-app
ib init

# 2. Smart create with AI
ib smart-add "需要一个 SaaS 应用，支持用户注册、订阅管理、计费系统"

# AI creates:
# ✓ src/models/User.ts
# ✓ src/models/Subscription.ts
# ✓ src/routes/auth.ts
# ✓ src/routes/subscriptions.ts
# ✓ package.json
# ✓ tsconfig.json
# ✓ README.md
# ✓ Requirement REQ-001

# 3. Continue adding requirements
ib do "添加用户资料编辑功能"
ib do "添加团队协作功能"

# 4. View all requirements
ib req list

# 5. Start implementing
ib req update REQ-001 --status implementing
ib map add REQ-001 src/user/UserService.ts

# 6. Validate completion
ib ai validate REQ-001 --with-code

Example 2: Multi-Project Workflow

# Register all projects
cd ~/projects/frontend
ib project register --name "frontend" --tags "react,typescript"

cd ~/projects/backend
ib project register --name "backend" --tags "nodejs,express"

cd ~/projects/mobile
ib project register --name "mobile" --tags "react-native"

# View global status
ib global-status

# Link related projects
ib project link frontend backend

# Share common utilities
ib share-file backend "src/utils/validation.ts" "frontend"

# View requirements across all projects
ib global-reqs --status implementing

Example 3: Claude Code Integration

# Method 1: MCP Server (Automated)
ib mcp-server start

# Claude Code can now directly call IntentBridge tools:
# - add_requirement
# - list_requirements
# - get_requirement
# - update_requirement_status

# Method 2: Manual Export
ib mcp export REQ-001
# Copy output and paste into Claude Code

# Claude Code sees:
# - Requirement details
# - Understanding
# - Related files
# - Recent decisions
# - Token budget

Example 4: Change Impact Analysis

# Requirement needs to change
ib analyze-impact REQ-001

# Output:
# Direct Dependencies: None
# Transitive Dependencies: REQ-002, REQ-003
# Affected Files: 5
# Impact Depth: 2
#
# Recommendation: Continue in current session
# Suggested Strategy: CONTINUE

# If impact is large, export to new session:
ib mcp export REQ-001
# → Paste into new Claude Code session

🏗️ Architecture

Progressive Understanding System

L0: Raw Requirement
    ↓ "User Authentication"
L1: Standardized
    ↓ Tags, acceptance criteria, dependencies
L2: Structured Understanding
    ↓ Generated markdown document
L3: AI-Enhanced
    ↓ AI-generated analysis, suggestions
L4: Code-Anchored
    ↓ Comments injected into source files

Context Flow

User Input
    ↓
[NLP Router] → Parse Intent
    ↓
[Project Detector] → Auto-detect context
    ↓
[Smart Analyzer] → AI analysis + structure creation
    ↓
[IntentBridge Store] → Persist requirements
    ↓
[MCP Bridge] → Export to Claude Code

📊 Comparison

Feature	IntentBridge	Jira	Linear	Notion
AI-Powered Understanding	✅	❌	❌	❌
Natural Language Interface	✅	❌	❌	❌
Claude Code Integration	✅	❌	❌	❌
Auto Project Scaffolding	✅	❌	❌	❌
Progressive Context	✅	❌	❌	❌
Offline-First	✅	❌	❌	✅
Developer-Centric	✅	❌	✅	❌
Free & Open Source	✅	❌	❌	✅

🛠️ Advanced Usage

Custom Templates

Create custom requirement templates:

# .intentbridge/templates/my-template.yaml
title: ""
description: ""
priority: medium
tags: []
acceptance:
  - criterion: ""
    done: false

Use it:

ib req add --template my-template

Git Hooks

Auto-sync file mappings with git:

# .git/hooks/post-checkout
#!/bin/sh
ib sync

📝 License

🆘 Support

🌟 Star History

If you find IntentBridge useful, please consider giving it a star ⭐️!

Built with ❤️ for Claude Code developers

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 83 Commits
.husky		.husky
bin		bin
docs		docs
scripts		scripts
sdk		sdk
src		src
tests		tests
web-server		web-server
web		web
.dockerignore		.dockerignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.lintstagedrc.json		.lintstagedrc.json
.npmignore		.npmignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
DEFICIENCIES_ANALYSIS.md		DEFICIENCIES_ANALYSIS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
docker-compose.yml		docker-compose.yml
install.sh		install.sh
jest.config.cjs		jest.config.cjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

🌉 IntentBridge

📖 Overview

Why IntentBridge?

✨ Features

🎯 Core Capabilities

🚀 Key Innovations

📦 Installation

One-Line Install (Recommended)

Prerequisites

Verify Installation

🎮 Quick Start

1. Initialize a Project

2. Add Your First Requirement

3. View Requirements

4. Work with Claude Code

5. Validate Completion

6. Visualize with Web UI (NEW! 🎉)

7. Multi-Project Coordination (NEW! v3.4.0 🚀)

📚 Documentation

🚀 Quick Start & Help

📚 Practical Tutorials (NEW! v3.5.0)

💡 Smart Commands (NEW! v3.5.0)

📦 Installation

Core Commands

Requirement Management

File Mapping

Milestones

AI Features

Multi-Project Management

Natural Language Interface

Smart Analysis

MCP Integration

Auto Detection

💡 Examples

Example 1: New Project from Scratch

Example 2: Multi-Project Workflow

Example 3: Claude Code Integration

Example 4: Change Impact Analysis

🏗️ Architecture

Progressive Understanding System

Context Flow

📊 Comparison

🛠️ Advanced Usage

Custom Templates

Git Hooks

📝 License

🆘 Support

🌟 Star History

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages