@pcircle/claude-code-buddy-mcp 2.5.2 → 2.6.0

package/README.md

@@ -1,292 +1,197 @@
-# Claude Code Buddy (CCB)
-
-🌐 **Website:** [ccb.pcircle.ai](https://ccb.pcircle.ai) | **Languages:** English | [繁體中文](README.zh-TW.md)
-
----
-
-> **Make Claude Code remember your project, learn from your feedback, and give you expert-level responses without expert-level prompts.**
-
-Claude Code Buddy is a Claude Code Plugin that adds intelligence, memory, and task routing to Claude Code - turning it from a powerful assistant into a project-aware AI teammate.
+<div align="center">
 
----
+# 🧠 Claude Code Buddy (CCB)
 
-## The Problem
+### **The Only MCP Server That Remembers**
 
-You're using Claude Code to build your project, but you keep hitting the same frustrations:
+**Make Claude Code remember everything. Build faster. Vibe harder.**
 
-- **"Didn't we already discuss this?"** - Claude forgets context between sessions
-- **"Why am I explaining this again?"** - Every conversation starts from zero
-- **"This answer is too generic"** - Same response whether you're debugging, reviewing code, or designing UI
-- **"Let me write this 50-line prompt... again"** - Repetitive instructions for common tasks
+[![GitHub Stars](https://img.shields.io/github/stars/PCIRCLE-AI/claude-code-buddy?style=social)](https://github.com/PCIRCLE-AI/claude-code-buddy)
+[![npm version](https://img.shields.io/npm/v/@pcircle/claude-code-buddy-mcp)](https://www.npmjs.com/package/@pcircle/claude-code-buddy-mcp)
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-1.25.3-purple.svg)](https://modelcontextprotocol.io)
 
-**You end up being Claude's memory and project manager instead of focusing on building.**
+[🚀 Quick Start](#-2-minute-quick-start) • [📖 Docs](docs/) • [🌐 Website](https://ccb.pcircle.ai) • [💬 Discussions](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
 
 ---
 
-## The Solution
+### 🎥 **See It In Action** (Interactive Demo)
 
-Claude Code Buddy sits between you and Claude Code, adding three superpowers:
+<table>
+<tr>
+<td width="50%" valign="top">
 
-### 1. 🧠 **Project Memory**
+#### 🔴 **Without CCB**
 
-CCB remembers your architecture decisions, coding patterns, and past solutions. Ask "Why did we choose PostgreSQL?" and get the actual decision rationale - not a generic comparison.
+```bash
+# Session 1 (Monday)
+You: "We use JWT for auth because..."
+Claude: "Got it! ✅"
 
-### 2. 🎯 **Smart Task Routing**
+# Session 2 (Tuesday)
+You: "Remember our auth approach?"
+Claude: "Sorry, I don't have context..."
+You: *explains everything again* 😤
 
-Your request gets analyzed and routed to the right "expert mode" - code review tasks get code review expertise, debugging gets systematic debugging methodology, frontend gets UI/UX best practices.
+# Session 3 (Wednesday)
+You: "Our JWT implementation..."
+Claude: "What JWT implementation?"
+You: *RAGE QUITS* 💢
+```
 
-### 3. 🎯 **Capability Guidance**
+</td>
+<td width="50%" valign="top">
 
-CCB tailors prompts to the task type and your project context, so reviews, debugging, and design work all get the right structure and guardrails.
+#### ✅ **With CCB**
 
-**Result:** Expert responses without expert prompts. Context that persists. Guidance that stays focused and actionable.
+```bash
+# Session 1 (Monday)
+You: buddy-do "setup JWT auth"
+CCB: ✅ Implemented + Saved to memory
 
-### What does "evolves with your project" actually mean?
+# Session 2 (Tuesday)
+You: buddy-remember "auth"
+CCB: 📚 "JWT auth implemented on 2024-01-15
+     ↳ Access tokens: 15min
+     ↳ Refresh tokens: 7 days
+     ↳ Secret rotation: monthly"
 
-CCB does not retrain models or modify Claude itself.
+# Session 3 (Any day, forever)
+You: buddy-do "add OAuth"
+CCB: 🧠 "I see you have JWT. Let's
+     integrate OAuth alongside it..."
+```
 
-Instead, evolution comes from a **persistent system layer** inside the Claude Code plugin:
+</td>
+</tr>
+</table>
 
-• **Project memory accumulation**
-Architectural decisions, conventions, and resolved discussions are stored as structured context.
+<div align="center">
 
-• **Pattern reinforcement**
-Repeated approvals, refactors, and preferred solutions gradually shape how future prompts are constructed.
+**💡 Try it yourself:**
 
-• **Task-type differentiation**
-Review, debugging, refactoring, and design tasks are handled with different internal prompting strategies.
+```bash
+# In Claude Code/Cursor
+buddy-help                          # See all commands
+buddy-do "explain how CCB works"    # Watch it intelligently respond
+buddy-remember "project decisions"  # Query your project memory
+```
 
-• **Context reuse, not repetition**
-Relevant memory is selectively injected, avoiding prompt bloat while preserving continuity.
+**📖 [Read User Guide](docs/USER_GUIDE.md)** • **🔧 [API Reference](docs/api/API_REFERENCE.md)**
 
-Over time, Claude Code responses become:
-• more aligned with your conventions
-• more consistent across sessions
-• less dependent on verbose prompts
+</div>
 
-This is *behavioral evolution through system memory and routing*, not model fine-tuning.
+</div>
 
 ---
 
-## See It In Action
+## 🤔 The Problem
 
-**Without CCB:**
+You know this pain:
 
 ```
-You: "Optimize this database query"
-Claude: [Generic advice about indexes and query structure]
+Session 1: "Let me explain our architecture..."
+Session 2: "As I mentioned before, our architecture..."
+Session 3: "Like I said earlier, our architecture..."
+Session 4: 😤
 ```
 
-**With CCB:**
-
-```
-You: "Optimize this database query"
-
-CCB analyzes: Database optimization task
-CCB routes to: database optimization capability
-CCB enhances prompt with: DB best practices, indexing strategies, profiling techniques
-
-Claude: [Specific optimization for YOUR database setup, with actual query examples
-         and performance benchmarks based on your schema]
-```
-
-**The difference:** CCB knows your stack, remembers your schema, and delivers targeted expertise.
+**Every. Single. Session.**
 
 ---
 
-## How to Use CCB
-
-After installation, CCB works **two ways**:
-
-### 🔄 Automatic Mode (Just Talk Normally)
+## ✨ The Solution
 
-CCB enhances your requests automatically in the background. No special commands needed:
-
-```
-You: "Review this code for security issues"
-     ↓
-CCB automatically:
-  • Detects task type → code review
-  • Routes to → security review capability
-  • Enhances prompt with → security checklist, best practices
-     ↓
-Claude responds with specialized security expertise
-```
+<table>
+<tr>
+<td width="50%" valign="top">
 
-**Just use Claude Code as usual** - CCB works invisibly to improve responses.
+### ❌ **Before CCB**
 
-### 🎮 Buddy Commands (Explicit Control)
+- Re-explain architecture every session
+- Answer same questions repeatedly
+- Forget design decisions overnight
+- Write similar prompts over and over
+- Claude has amnesia 🤕
 
-Use these commands when you want specific CCB features:
+</td>
+<td width="50%" valign="top">
 
-| Command | What It Does | Example |
-|---------|--------------|---------|
-| `buddy-do` | Execute task with smart routing | `buddy-do "setup user authentication"` |
-| `buddy-remember` | Search project memory | `buddy-remember "why did we choose PostgreSQL"` |
-| `buddy-help` | Get help on any command | `buddy-help remember` |
+### ✅ **After CCB**
 
-### 💾 Project Memory
+- **Remembers** project architecture
+- **Recalls** past decisions instantly
+- **Organizes** knowledge automatically
+- **Routes** tasks intelligently
+- Claude becomes your AI teammate 🤝
 
-Project memory is captured automatically as you work. Use `buddy-remember` to recall key decisions and recent progress.
-
-Project memory is automatic. Use `buddy-remember` to recall decisions, patterns, and recent work.
-
-### 📋 Quick Reference Card
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  CCB QUICK REFERENCE                                        │
-├─────────────────────────────────────────────────────────────┤
-│  🔄 AUTOMATIC (just talk normally)                          │
-│     • "Review this code" → routes to code review            │
-│     • "Debug this error" → routes to debugging              │
-│     • "Design a component" → routes to UI design            │
-├─────────────────────────────────────────────────────────────┤
-│  🎮 BUDDY COMMANDS                                          │
-│     buddy-do "task"         Execute with smart routing      │
-│     buddy-remember "query"  Search project memory           │
-│     buddy-help [command]    Get help                        │
-├─────────────────────────────────────────────────────────────┤
-│  🧭 WORKFLOW                                                 │
-│     get-session-health     Check context health             │
-│     get-workflow-guidance  Get next-step recommendations    │
-│     generate-smart-plan    Create implementation plans      │
-└─────────────────────────────────────────────────────────────┘
-```
+</td>
+</tr>
+</table>
 
 ---
 
-## Key Features
-
-### ✨ Automatic Expertise Routing
-
-CCB routes requests to internal specialists based on capability signals. You describe intent, CCB handles routing.
+## 🎯 Core Features
 
-**Capabilities include:**
-- Code review, security audits, and best-practice validation
-- Debugging and root-cause analysis
-- Refactoring and technical debt reduction
-- API design, backend architecture, and database optimization
-- Testing strategy and generation
-- Performance profiling and optimization
-- UI/UX design and technical writing
-- Research, product, and planning support
+### 1. 🧠 **Project Memory That Actually Works**
 
-### 💾 Memory Systems
-
-**Knowledge Graph**
-
-```
-You: "Why did we choose this architecture?"
-CCB: [Recalls the decision, the alternatives considered, and the tradeoffs]
-```
-
-**Project Context**
+```bash
+# Session 1 (Last week)
+You: "We chose PostgreSQL for JSONB support"
 
+# Session 42 (Today)
+You: buddy-remember "why PostgreSQL?"
+CCB: "Based on your decision from 2024-01-15: PostgreSQL was
+      chosen for JSONB support and advanced query capabilities..."
 ```
-CCB remembers:
-- Your coding standards
-- Naming conventions
-- Project-specific patterns
-- What you've already built
-```
-
-### 🎯 Capability Guidance & Prompt Focus
-
-CCB analyzes task complexity and routes to the right internal capability, shaping prompts for reviews, debugging, planning, or UI/UX work.
-
-**How it works**: TaskAnalyzer examines your request → Estimates complexity (1-10) → Routes to the best capability profile → You get focused guidance without over-tuning prompts.
 
-**Real example**: "Fix this typo" gets a fast, minimal path, while "Design authentication system" gets a structured architecture workflow and risk checklist.
+**Claude remembers. Forever.**
 
-### 🤝 User-Friendly Commands
+### 2. 🎯 **Smart Task Routing (Autopilot Mode)**
 
 ```bash
-# Simple commands that just work
-buddy-do "setup authentication"
-buddy-do "optimize this database query"
-buddy-remember "how we implemented login"
-buddy-help
+You: "Review this code"
+CCB: *Detects task type*
+     *Activates code review mode*
+     *Applies best practices*
+     *Delivers structured review*
 ```
 
-### 🔄 Intelligent Workflow Guidance
+**No more "how should I do this?" Just do it.**
 
-**CCB knows what's next.** After you write code, it suggests running tests. After tests pass, it suggests code review. No manual thinking required.
+### 3. 💬 **Dead Simple Commands**
 
-```
-You write code → CCB: "Code looks good! Run tests next?"
-Tests pass → CCB: "Tests green! Ready for code review?"
-Review done → CCB: "Review complete! Commit and push?"
+```bash
+buddy-do "setup authentication"     # Execute any dev task
+buddy-remember "API design"         # Query project memory
+buddy-help                          # When stuck
 ```
 
-**Workflow tools:**
+**Three commands. Infinite possibilities.**
 
-- `get-workflow-guidance` - Get next-step recommendations
-- `get-session-health` - Check session health status
+---
 
-**Benefits:** Never wonder "what should I do next?" - CCB guides you through the complete development flow.
+## 🚀 2-Minute Quick Start
 
-### 📋 Smart Implementation Planning
+### Step 1: Install (Choose Your IDE)
 
-**Break down complex features into bite-sized tasks.** CCB generates TDD-structured plans with capability-aware task breakdown.
+<details>
+<summary><strong>🎯 Cursor Users</strong> (Click to expand)</summary>
 
+Just click this magic link:
 ```
-You: "Plan implementation for user authentication"
-CCB: [Generates step-by-step plan with:
-  - Test-first approach
-  - 2-5 minute tasks
-  - Right capability for each task
-  - Clear success criteria]
-```
-
-**Planning tool:**
-
-- `generate-smart-plan` - Create intelligent implementation plans
-
-### 🔒 Security & Reliability
-
-**Built with security and stability as core principles.**
-
-**Security Hardening:**
-- ✅ **API Key Validation**: Comprehensive format validation prevents runtime failures
-- ✅ **Input Sanitization**: Blocks NaN, Infinity, and malicious input values (DoS prevention)
-- ✅ **SQL Injection Protection**: Pure parameterization with JSON functions (no string concatenation)
-- ✅ **Logging Sanitization**: 50+ patterns to redact API keys, tokens, credentials, PII from logs
-- ✅ **Path Traversal Prevention**: Validates database paths, resolves symlinks, enforces directory boundaries
-- ✅ **Zero Vulnerabilities**: Regular `npm audit` with immediate dependency updates
-
-**Reliability:**
-- ✅ **1226 Tests Passing**: Comprehensive test coverage across all components
-- ✅ **Timer Leak Prevention**: Proper cleanup in all async operations
-- ✅ **Race Condition Protection**: Systematic concurrency testing and prevention
-- ✅ **Graceful Error Handling**: Detailed error messages with recovery suggestions
-
-**Latest Security Audit (v2.3.5):**
-```bash
-npm audit
-# Result: 0 vulnerabilities found ✅
+cursor://anysphere.cursor-deeplink/mcp/install?name=@pcircle/claude-code-buddy-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwY2lyY2xlL2NsYXVkZS1jb2RlLWJ1ZGR5LW1jcCJdfQ==
 ```
 
----
-
-## Quick Start (2 Minutes)
+**Done.** Restart Cursor and you're ready.
 
-### 🚀 One-Click Installation
+</details>
 
-#### For Cursor Users
+<details>
+<summary><strong>⚡ Claude Code Users</strong> (Click to expand)</summary>
 
-<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=@pcircle/claude-code-buddy-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwY2lyY2xlL2NsYXVkZS1jb2RlLWJ1ZGR5LW1jcCJdfQ==">
-  <img src="https://cursor.com/deeplink/mcp-install-dark.png" alt="Add to Cursor" />
-</a>
+Add this to `~/.claude/mcp_settings.json`:
 
-**Click the button above or paste this link in your browser:**
-```
-cursor://anysphere.cursor-deeplink/mcp/install?name=@pcircle/claude-code-buddy-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwY2lyY2xlL2NsYXVkZS1jb2RlLWJ1ZGR5LW1jcCJdfQ==
-```
-
-#### For VS Code / Claude Code Users
-
-**Quick MCP Configuration** (add to `~/.claude/mcp_settings.json`):
 ```json
 {
   "mcpServers": {
@@ -298,329 +203,289 @@ cursor://anysphere.cursor-deeplink/mcp/install?name=@pcircle/claude-code-buddy-m
 }
 ```
 
-Then restart Claude Code and start using CCB!
-
-**📖 Detailed installation guide**: See [QUICK_INSTALL.md](docs/QUICK_INSTALL.md)
-
-### 🔧 Process Management (Optional)
+**Restart Claude Code** and you're golden.
 
-CCB MCP server runs as a background process for each Claude Code CLI session. Normally, this is transparent and requires no action. However, you may want to manage processes when:
+</details>
 
-- Upgrading to a new version
-- Debugging connection issues
-- Cleaning up orphaned processes
+### Step 2: Test It
 
-**Quick Commands:**
 ```bash
-# List all CCB MCP processes
-npm run processes:list
-
-# Check for orphaned processes
-npm run processes:orphaned
+# In Claude Code/Cursor, type:
+buddy-help
 
-# Clean up all CCB MCP processes
-npm run processes:kill
+# You should see CCB's command list
+# Now try:
+buddy-do "explain CCB features"
 
-# Check MCP configuration
-npm run processes:config
+# Watch the magic happen ✨
 ```
 
-**📖 Detailed process management guide**: See [MCP_PROCESS_MANAGEMENT.md](docs/MCP_PROCESS_MANAGEMENT.md)
+**🎉 That's it! You're vibing now.**
 
----
+📖 **Need help?** [Detailed installation guide](docs/QUICK_INSTALL.md) | [Troubleshooting](docs/TROUBLESHOOTING.md)
 
-### Prerequisites
+---
 
-- Node.js 20+ ([download](https://nodejs.org/))
-- Claude Code installed ([get it here](https://claude.com/claude-code)) or Cursor IDE
+## 💡 Real-World Usage
 
-### Manual Installation (Alternative)
+### Scenario 1: **Building a New Feature**
 
 ```bash
-# 1. Clone the repository
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
+You: buddy-do "create a real-time chat with WebSocket"
 
-# 2. Run the interactive installer (it handles everything)
-./scripts/install.sh
-```
+CCB analyzes your project...
+🔍 Detected: React + Node.js + Express
+🧠 Recalled: Your preference for TypeScript strict mode
+📝 Applying: Error boundaries pattern from LoginPage.tsx
 
-The installer guides you through **9 interactive steps**:
+✅ Generated:
+   ├─ server/chat.ts (WebSocket server)
+   ├─ components/ChatWindow.tsx (React component)
+   └─ hooks/useWebSocket.ts (Custom hook)
 
-**Core Setup (Steps 1-7)**:
+💾 Saved to memory: "WebSocket chat architecture - 2024-01-20"
+```
 
-- ✓ Check prerequisites (Node.js 20+, npm; git optional)
-- ✓ Install dependencies
-- ✓ Build the project
-- ✓ Check system resources
-- ✓ Configure environment
-- ✓ Configure Claude Code MCP integration
-- ✓ Test installation
+### Scenario 2: **"Wait, Why Did We Do That?"**
 
-**Interactive Demos (Steps 8-9)**:
+```bash
+You: buddy-remember "authentication approach"
 
-- 📚 **Step 8: Basic Usage Demo** - Learn about CCB's smart routing, example prompts, and memory features
-- ✅ **Step 9: MCP Verification** - Confirm the MCP server is reachable
+CCB searches knowledge graph...
 
-**No API keys needed in MCP server mode** - uses your existing Claude Code subscription.
+📚 Found 3 related memories:
 
-**Optional configuration** (only if you want to change defaults):
-```bash
-cp .env.example .env
-# For standalone orchestrator usage:
-# MCP_SERVER_MODE=false
-# ANTHROPIC_API_KEY=your_key_here
-# Optional guidance modes:
-# BEGINNER_MODE=true
-# EVIDENCE_MODE=true
+┌─ 2024-01-15: Initial Auth Decision
+│  💬 "JWT chosen over sessions for stateless API"
+│  ⚡ Reasoning: Mobile app compatibility
+│
+├─ 2024-01-18: Token Expiry Implementation
+│  💻 Code: auth/middleware.ts:42-67
+│  🔧 Access: 15min | Refresh: 7 days
+│
+└─ 2024-01-22: Security Enhancement
+   🛡️ Added: Rate limiting + Token rotation
+   📝 Prevented: Token reuse vulnerability
 ```
 
-### Start Using It
-
-Restart Claude Code, then try:
+### Scenario 3: **Continuous Development Flow**
 
 ```
-"Analyze my codebase architecture"
-"Generate tests for auth.ts"
-"Review this code for security issues"
-"Optimize this database query"
+Day 1 │  You: "Implement user login"
+      │  CCB: ✅ Created + 💾 Remembered
+      │
+Day 5 │  You: "Add password reset"
+      │  CCB: 🧠 "I see you use JWT tokens..."
+      │       ✅ Integrated seamlessly
+      │
+Day 10│  You: "Add OAuth support"
+      │  CCB: 🧠 "Based on your JWT + password reset..."
+      │       ✅ Consistent with existing auth
+      │
+Week 8│  You: "Why did we choose JWT again?"
+      │  CCB: 📚 *Instant recall from Day 1*
 ```
 
-CCB automatically routes tasks to the right capability and enhances prompts with relevant context.
+**No context re-explanation. Ever again.**
 
 ---
 
-## How It Works
-
-```
-Your Request
-    ↓
-CCB analyzes the task
-    ↓
-Routes to best capability type (e.g., code review, debugging)
-    ↓
-Enhances prompt with specialized context
-    ↓
-Claude Code executes with your subscription
-    ↓
-System learns from your choices (when you override recommendations)
-```
-
-**Under the hood:**
+## 📊 Why CCB vs. Others?
 
-- **Curated internal specialists** handle routing and prompt construction
-- **Smart routing** analyzes task complexity and automatically selects the right Claude model
-- **Evolution system** learns from your choices and continuously improves recommendations
-
-**Technical deep dive:** See [docs/README.md](docs/README.md)
+| Feature | Plain Claude Code | Other MCP Tools | CCB |
+|---------|-------------------|-----------------|-----|
+| **Persistent Memory** | ❌ | ⚠️ Basic | ✅ **Full Knowledge Graph** |
+| **Smart Routing** | ❌ | ❌ | ✅ **Auto-detects task type** |
+| **Vibe Coding Optimized** | ⚠️ | ❌ | ✅ **Built for it** |
+| **Zero Setup** | ✅ | ⚠️ Complex | ✅ **2 minutes** |
+| **Free & Open Source** | ✅ | ⚠️ Varies | ✅ **AGPL-3.0** |
 
 ---
 
-## What CCB Does Well ✅
+## 🛠️ Advanced Features
 
-- **Makes Claude Code context-aware** for your specific project
-- **Reduces repetitive prompting** through intelligent task routing
-- **Remembers between sessions** with persistent memory systems (Knowledge Graph + Project Context)
-- **Provides specialized expertise** without you writing expert prompts
-- **Keeps responses focused** by routing to the right capability for each task
-- **Learns from your choices** when you override recommendations
-- **Guides your workflow** with intelligent next-step recommendations
-- **Reduces hallucinations** with evidence-first prompting and explicit assumptions
-- **Coordinates complex workflows** across multiple steps
-- **Cross-platform support** works seamlessly on Windows, macOS, and Linux
-- **Production-ready** with comprehensive testing, security hardening, and resource protection
+<details>
+<summary><strong>Auto-Memory System</strong></summary>
 
-## Honest Limitations ⚠️
+When you use `buddy-do`, CCB automatically records:
+- ✅ Task goals and outcomes
+- ✅ Technical decisions and reasoning
+- ✅ Errors encountered and solutions
+- ✅ Development milestones
 
-- **Not magic** - Still needs clear requirements from you
-- **Not a replacement for learning** - You should understand what you're building
-- **Enhances Claude Code, doesn't replace it** - Works alongside your existing setup
-- **Requires setup** - 2-minute install, not one-click (yet)
-- **Early stage (v2.2)** - Expect rough edges, but actively improving
-- **Limited by Claude's capabilities** - Can't make Claude do impossible things
+**You don't think about memory. CCB does.**
 
-**Philosophy:** We're honest about what works and what doesn't. If something doesn't work for you, let us know - that feedback makes it better for everyone.
+</details>
 
----
+<details>
+<summary><strong>Multi-Project Support</strong></summary>
 
-## Use Cases
+Each project gets its own isolated memory space.
 
-### Code Review
+```bash
+cd ~/project-A
+buddy-remember "auth"  # Returns project-A's auth decisions
 
-```
-"Review this PR for security vulnerabilities and code quality"
-→ Routes to code review capability
-→ Gets security checklist + quality standards
-→ Returns detailed review with specific recommendations
+cd ~/project-B
+buddy-remember "auth"  # Returns project-B's auth decisions
 ```
 
-### Debugging
+**No cross-contamination. Ever.**
 
-```
-"This function crashes with undefined, help debug"
-→ Routes to debugging capability
-→ Gets systematic debugging methodology
-→ Walks through root cause analysis step-by-step
-```
+</details>
 
-### Frontend Design
+<details>
+<summary><strong>17 MCP Standard Tools</strong></summary>
 
-```
-"Design a responsive dashboard with dark mode"
-→ Routes to UI design capability
-→ Gets UI/UX patterns + accessibility guidelines
-→ Returns complete design with responsive breakpoints
-```
+Full integration with Model Context Protocol.
 
-### Database Optimization
+See complete list: [ToolDefinitions.ts](src/mcp/ToolDefinitions.ts)
 
-```
-"This Prisma query takes 2 seconds, optimize it"
-→ Routes to database optimization capability
-→ Gets query optimization patterns + indexing strategies
-→ Returns optimized query with performance benchmarks
-```
+</details>
 
 ---
 
-## Advanced Features
+## 🧪 Technical Details
 
-- **Custom Skills** - Write your own routing behaviors in TypeScript
-- **Multi-step Planning** - Break down complex tasks into executable plans
-- **Workflow Coordination** - Automatic checkpoint detection and next-step suggestions
-- **Dashboard** - Real-time metrics, session health monitoring, performance tracking
+<table>
+<tr>
+<td width="50%">
 
-**Explore:** See [docs/](docs/) for detailed guides on each feature.
+### Requirements
+- Node.js 20+
+- Claude Code or Cursor IDE
+- 5 minutes of your time
 
----
+</td>
+<td width="50%">
 
-## Technical Specifications
+### Platform Support
+- ✅ **Claude 4.5** (Haiku/Sonnet/Opus)
+- ✅ **MCP SDK 1.25.3**
+- ✅ Windows, macOS, Linux
 
-### Claude 4.5 Model Support
+</td>
+</tr>
+</table>
 
-CCB fully supports the latest Claude 4.5 model family:
+### 🔒 Security First
 
-- **Claude Haiku 4.5** (claude-haiku-4-5-20251015) - Fast responses for simple tasks
-  - Pricing: $1.00 input / $5.00 output per MTok
-  - Use case: Quick queries, simple refactors, code formatting
+- ✅ **100% Local Processing** - Your data never leaves your machine
+- ✅ **No External API Calls** - Uses your Claude Code subscription
+- ✅ **npm audit: 0 vulnerabilities**
+- ✅ **Open Source** - Audit the code yourself
 
-- **Claude Sonnet 4.5** (claude-sonnet-4-5-20250929) - Balanced performance for daily development
-  - Use case: Code generation, testing, moderate complexity tasks
+---
 
-- **Claude Opus 4.5** (claude-opus-4-5-20251101) - Deep reasoning for complex challenges
-  - Use case: Architecture design, complex debugging, creative problem-solving
+## 🤝 Contributing
 
-**Smart Model Selection:** CCB automatically selects the appropriate model based on task complexity, optimizing for both quality and cost.
+We'd love your help making CCB better!
 
-### MCP Specification Compliance
+- 🐛 **Found a bug?** [Open an issue](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
+- 💡 **Have an idea?** [Start a discussion](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
+- 🛠️ **Want to code?** Check [Good First Issues](https://github.com/PCIRCLE-AI/claude-code-buddy/labels/good%20first%20issue)
 
-✅ **Full compliance with MCP Specification 2025-11-25**
+**Contributing Guide**: [CONTRIBUTING.md](docs/CONTRIBUTING.md)
 
-All MCP tools include:
-- **Tool Annotations**: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`
-- **Output Schemas**: Structured JSON schemas for type-safe responses
-- **Runtime Validation**: Automatic validation of tool inputs and outputs
+---
 
-**7 MCP Tools Available:**
-1. `buddy-do` - Smart task execution with capability routing
-2. `buddy-remember` - Project memory recall
-3. `buddy-help` - Command documentation
-4. `get-session-health` - Session monitoring and diagnostics
-5. `get-workflow-guidance` - Intelligent workflow recommendations
-6. `generate-smart-plan` - Implementation plan generation
-7. `hook-tool-use` - Tool usage event tracking
+## 📚 Documentation
 
-See [src/mcp/ToolDefinitions.ts](src/mcp/ToolDefinitions.ts) for complete tool specifications.
+- 📖 [Full Documentation](docs/)
+- 🚀 [Quick Install Guide](docs/QUICK_INSTALL.md)
+- 📘 [User Guide](docs/USER_GUIDE.md)
+- 🛠️ [API Reference](docs/api/API_REFERENCE.md)
+- ❓ [Troubleshooting](docs/TROUBLESHOOTING.md)
 
 ---
 
-## Community & Support
+## ❓ FAQ
 
-- **Documentation**: [docs/](docs/) folder + this README
-- **Issues**: [GitHub Issues](https://github.com/PCIRCLE-AI/claude-code-buddy/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
-- **Contributing**: [CONTRIBUTING.md](docs/CONTRIBUTING.md)
+<details>
+<summary><strong>Q: Does it cost money?</strong></summary>
 
-**Questions?** Open an issue or start a discussion - we're here to help.
+**A:** Nope. 100% free and open source (AGPL-3.0). Uses your existing Claude Code subscription.
 
----
+</details>
 
-## Development
+<details>
+<summary><strong>Q: Is my data safe?</strong></summary>
 
-```bash
-# Run tests (292 test files covering core functionality)
-npm test
+**A:** Yes. Everything processed locally. Zero external API calls. Zero data upload.
 
-# Development mode with auto-reload
-npm run dev
+</details>
 
-# Build for production
-npm run build
+<details>
+<summary><strong>Q: How is this different from plain Claude Code?</strong></summary>
 
-# View performance dashboard
-npm run dashboard
-```
+**A:** CCB adds two superpowers:
+1. **Persistent Memory** - Claude remembers your project across sessions
+2. **Smart Routing** - Automatically detects and handles different task types
 
-**Contributing:** We welcome contributions! See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.
+Think of it as Claude Code + a really good memory + autopilot mode.
 
-**Project Structure:** See [docs/README.md](docs/README.md) for a documentation map.
+</details>
 
----
+<details>
+<summary><strong>Q: Can I customize it?</strong></summary>
 
-## FAQ
+**A:** Absolutely. Prompt templates in `src/core/PromptEnhancer.ts`.
 
-**Q: Do I need to be a developer to use this?**
-A: If you can use Claude Code, you can use CCB. It's designed to make Claude easier, not harder.
+Want deeper customization? Fork it, hack it, make it yours. That's the open source way.
 
-**Q: Does this cost extra on top of Claude Code?**
-A: No - CCB uses your existing Claude Code subscription. It helps optimize token usage within your session limits, not API costs.
+</details>
 
-**Q: How is this different from just using Claude Code?**
-A: Claude Code treats every task the same. CCB adds task-specific expertise, memory, and learning.
+<details>
+<summary><strong>Q: Does it work with Cursor?</strong></summary>
 
-**Q: Is my code private?**
-A: Yes. Everything runs locally through your Claude Code subscription. CCB does not require external AI services.
+**A:** Yes! Cursor has native MCP support. One-click install.
+
+</details>
+
+---
 
-**Q: What if I don't like it?**
-A: Remove it from your MCP config. No lock-in, no vendor dependency.
+## 🙏 Acknowledgments
 
-**Q: How much does it cost?**
-A: CCB is free and open-source (AGPL-3.0). It works with your existing Claude Code subscription.
+Built on the shoulders of giants:
 
-**Q: Can I customize routing behavior?**
-A: Absolutely! Prompt templates are in `src/core/PromptEnhancer.ts`. Evolution config in `src/evolution/AgentEvolutionConfig.ts`.
+- [Model Context Protocol (MCP)](https://github.com/anthropics/mcp) - The foundation
+- [Claude Code](https://claude.com/claude-code) - The platform
+- All our amazing [contributors](https://github.com/PCIRCLE-AI/claude-code-buddy/graphs/contributors) and early testers
 
 ---
 
-## License
+## 📄 License
 
-**AGPL-3.0 License** - see [LICENSE](LICENSE) file for details.
+**AGPL-3.0** - See [LICENSE](LICENSE)
 
-This is free and open-source software. If you modify and deploy this as a network service, you must make the source code available to users.
+*This means: Use it, modify it, share it. But keep it open source.*
 
 ---
 
-## Acknowledgments
+## 🌟 Star History
 
-- Built with [Model Context Protocol (MCP)](https://github.com/anthropics/mcp)
-- Works with [Claude Code](https://claude.com/claude-code)
-- Inspired by the Claude Code community
-- Thanks to all contributors and early testers
-
-**Disclaimer:** This is an independent open-source project and is not affiliated with, endorsed by, or officially connected to Anthropic PBC or its products (including Claude and Claude Code). Claude Code Buddy is a third-party tool designed to integrate with Claude Code.
+[![Star History Chart](https://api.star-history.com/svg?repos=PCIRCLE-AI/claude-code-buddy&type=Date)](https://star-history.com/#PCIRCLE-AI/claude-code-buddy&Date)
 
 ---
 
 <div align="center">
 
-**Built with ❤️ by developers, for developers.**
+### **Built by developers, for developers**
+
+**Stop repeating yourself. Start vibing.**
+
+[🚀 Get Started](#-2-minute-quick-start) • [📖 Read the Docs](docs/) • [💬 Join the Discussion](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
 
-**Make Claude Code smarter, not louder.**
+---
+
+### ⭐ **If CCB saved you time today, give it a star!**
 
-[Get Started](#quick-start-2-minutes) • [Documentation](docs/) • [Report Issue](https://github.com/PCIRCLE-AI/claude-code-buddy/issues) • [Join Discussion](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
+It helps others discover this tool.
 
 ---
 
-⭐ **Star this repo if CCB makes your development life easier!**
+**Not affiliated with Anthropic PBC** • Independent open-source project
+
+**Languages:** [English](README.md) • [繁體中文](README.zh-TW.md)
 
 </div>