🌐 Website: ccb.pcircle.ai | Languages: English | 繁體中文
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.
You're using Claude Code to build your project, but you keep hitting the same frustrations:
- "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
You end up being Claude's memory and project manager instead of focusing on building.
Claude Code Buddy sits between you and Claude Code, adding three superpowers:
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.
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.
CCB tailors prompts to the task type and your project context, so reviews, debugging, and design work all get the right structure and guardrails.
Result: Expert responses without expert prompts. Context that persists. Guidance that stays focused and actionable.
CCB does not retrain models or modify Claude itself.
Instead, evolution comes from a persistent system layer inside the Claude Code plugin:
• Project memory accumulation Architectural decisions, conventions, and resolved discussions are stored as structured context.
• Pattern reinforcement Repeated approvals, refactors, and preferred solutions gradually shape how future prompts are constructed.
• Task-type differentiation Review, debugging, refactoring, and design tasks are handled with different internal prompting strategies.
• Context reuse, not repetition Relevant memory is selectively injected, avoiding prompt bloat while preserving continuity.
Over time, Claude Code responses become: • more aligned with your conventions • more consistent across sessions • less dependent on verbose prompts
This is behavioral evolution through system memory and routing, not model fine-tuning.
Without CCB:
You: "Optimize this database query"
Claude: [Generic advice about indexes and query structure]
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.
After installation, CCB works two ways:
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
Just use Claude Code as usual - CCB works invisibly to improve responses.
Use these commands when you want specific CCB features:
| 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 |
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.
┌─────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────┘
CCB routes requests to internal specialists based on capability signals. You describe intent, CCB handles routing.
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
Knowledge Graph
You: "Why did we choose this architecture?"
CCB: [Recalls the decision, the alternatives considered, and the tradeoffs]
Project Context
CCB remembers:
- Your coding standards
- Naming conventions
- Project-specific patterns
- What you've already built
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.
# Simple commands that just work
buddy-do "setup authentication"
buddy-do "optimize this database query"
buddy-remember "how we implemented login"
buddy-helpCCB knows what's next. After you write code, it suggests running tests. After tests pass, it suggests code review. No manual thinking required.
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?"
Workflow tools:
get-workflow-guidance- Get next-step recommendationsget-session-health- Check session health status
Benefits: Never wonder "what should I do next?" - CCB guides you through the complete development flow.
Break down complex features into bite-sized tasks. CCB generates TDD-structured plans with capability-aware task breakdown.
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
- Node.js 20+ (download)
- Claude Code installed (get it here)
# 1. Clone the repository
git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
cd claude-code-buddy
# 2. Run the interactive installer (it handles everything)
./scripts/install.shThe installer guides you through 9 interactive steps:
Core Setup (Steps 1-7):
- ✓ 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
Interactive Demos (Steps 8-9):
- 📚 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
No API keys needed in MCP server mode - uses your existing Claude Code subscription.
Optional configuration (only if you want to change defaults):
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=trueRestart Claude Code, then try:
"Analyze my codebase architecture"
"Generate tests for auth.ts"
"Review this code for security issues"
"Optimize this database query"
CCB automatically routes tasks to the right capability and enhances prompts with relevant context.
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:
- 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
- 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
- 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
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.
"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
"This function crashes with undefined, help debug"
→ Routes to debugging capability
→ Gets systematic debugging methodology
→ Walks through root cause analysis step-by-step
"Design a responsive dashboard with dark mode"
→ Routes to UI design capability
→ Gets UI/UX patterns + accessibility guidelines
→ Returns complete design with responsive breakpoints
"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
- 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
Explore: See docs/ for detailed guides on each feature.
- Documentation: docs/ folder + this README
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Contributing: CONTRIBUTING.md
Questions? Open an issue or start a discussion - we're here to help.
# Run tests (292 test files covering core functionality)
npm test
# Development mode with auto-reload
npm run dev
# Build for production
npm run build
# View performance dashboard
npm run dashboardContributing: We welcome contributions! See CONTRIBUTING.md for guidelines.
Project Structure: See docs/README.md for a documentation map.
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.
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.
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.
Q: Is my code private? A: Yes. Everything runs locally through your Claude Code subscription. CCB does not require external AI services.
Q: What if I don't like it? A: Remove it from your MCP config. No lock-in, no vendor dependency.
Q: How much does it cost? A: CCB is free and open-source (AGPL-3.0). It works with your existing Claude Code subscription.
Q: Can I customize routing behavior?
A: Absolutely! Prompt templates are in src/core/PromptEnhancer.ts. Evolution config in src/evolution/AgentEvolutionConfig.ts.
AGPL-3.0 License - see LICENSE file for details.
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.
- Built with Model Context Protocol (MCP)
- Works with 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.
Built with ❤️ by developers, for developers.
Make Claude Code smarter, not louder.
Get Started • Documentation • Report Issue • Join Discussion
⭐ Star this repo if CCB makes your development life easier!