English | 한국어 | 中文 | 日本語 | Español

# Codingbuddy [![CI](https://github.com/JeremyDev87/codingbuddy/actions/workflows/dev.yml/badge.svg)](https://github.com/JeremyDev87/codingbuddy/actions/workflows/dev.yml) [![npm version](https://img.shields.io/npm/v/codingbuddy.svg)](https://www.npmjs.com/package/codingbuddy) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) **Prove your AI coding is actually improving.** Codingbuddy is a multi-AI MCP server that orchestrates 37 specialist agents across 9 AI tools — and measures the impact on your code quality with every session. --- ## What's New in v5.6.0 — HUD Statusbar Wave - **Breathing Buddy Face** — the buddy face reacts to your session phase (idle / thinking / active / blocked / victory) so the status bar feels alive. - **Cost Velocity Indicator** — session spend-rate badge with 🔥 / ↗ / → / 💤 trend glyphs tells you whether you're on a slow planning pass or a hot refactor burn. - **Cache Savings Badge** — quantifies prompt-cache discounts as `💰$N.NN saved` so you see the value of caching in real time. - **Mode Rainbow Coloring** — per-mode ANSI truecolor gradients (PLAN ◇ / ACT ◆ / EVAL ◈ / AUTO ◊) with `NO_COLOR` env support for CI and greyscale terminals. - **Smart Context Bar** — visual `[████░░░░░░] 42%` progress bar replaces plain `Ctx:42%` text with warning and danger thresholds. - **Adaptive Layout Engine** — HUD fits narrow terminals gracefully with `fit_segments` adaptive truncation. - **Rate-limit Severity Icons** — visual warnings when you approach API rate limits. --- ## Session Impact Report At the end of every session, codingbuddy shows you what actually happened: ``` ┌─────────────────────────────────────────────────┐ │ Session Impact Report │ ├─────────────────────────────────────────────────┤ │ │ │ Issues prevented 12 │ │ Security 4 (2 critical) │ │ Accessibility 3 │ │ Performance 2 │ │ Code Quality 3 │ │ │ │ Agents dispatched 8 │ │ Checklists generated 5 │ │ Mode transitions PLAN → ACT → EVAL │ │ Context decisions 14 │ │ │ └─────────────────────────────────────────────────┘ ``` Most AI rules tools tell you to "code better." Codingbuddy proves you did. --- ## Quick Start ```bash # 1. Install npm install -g codingbuddy # 2. Initialize your project npx codingbuddy init # 3. Add to your AI tool's MCP config ``` ```json { "mcpServers": { "codingbuddy": { "command": "npx", "args": ["codingbuddy", "mcp"] } } } ``` Start coding with `PLAN`, `ACT`, `EVAL`, or `AUTO` keywords. > **Claude Code users**: Install as a plugin for the full experience: > > ```bash > # 1. Add marketplace > claude marketplace add JeremyDev87/codingbuddy > > # 2. Install plugin > claude plugin install codingbuddy@jeremydev87 > ``` > > The plugin adds session-aware hooks that power Impact Reports, buddy greetings, onboarding tours, achievement badges, and adaptive performance mode. Update to the latest version with `claude plugin install codingbuddy@jeremydev87`. > > See the [Plugin Guide](docs/plugin-guide.md) for details. [Full Getting Started Guide →](docs/getting-started.md) --- ## Why Codingbuddy? **Measurable results, not promises.** Session Impact Reports show issues prevented, agents dispatched, and quality improvements — backed by data from every tool call. **37 specialists, not one generalist.** Security engineers, accessibility experts, performance specialists, architects — each with domain expertise that a single AI cannot match. **One ruleset, 9 AI tools.** Same quality standards whether you use Cursor, Claude Code, GitHub Copilot, or any other supported tool. Switch tools without losing consistency. **Quality gates that ship.** The PLAN → ACT → EVAL cycle iterates until Critical=0 and High=0. Production-ready code, not "good enough" code. --- ## What's New in v5.4.0 **Question-First Planning** — Codingbuddy now asks before it plans. Ambiguous prompts trigger a clarifying question, and clear prompts walk through Discover→Design→Plan stages with explicit user confirmation at each step. **Council Scene** — PLAN, EVAL, and AUTO modes open with a visible council scene showing which specialist agents are assembled and ready to collaborate. **Permission Forecast** — Before execution, codingbuddy surfaces what permission classes (repo-write, network, external) will be needed, so you can prepare approval bundles in advance. **Execution Gate** — When the planning stage hasn't advanced past discovery, specialist dispatch is suppressed to avoid premature work. **Council State Pipeline** — Real-time council badges show agent handoffs, stage transitions, and blockers as they happen during tool execution. --- ## Supported AI Tools | Tool | Integration | Setup | |------|-------------|-------| | Claude Code | MCP Server + Plugin | [Guide](packages/rules/.ai-rules/adapters/claude-code.md) | | Cursor | MCP Server | [Guide](packages/rules/.ai-rules/adapters/cursor.md) | | GitHub Copilot / Codex | MCP Server | [Guide](packages/rules/.ai-rules/adapters/codex.md) | | Antigravity (Gemini) | MCP Server | [Guide](packages/rules/.ai-rules/adapters/antigravity.md) | | Amazon Q | MCP Server | [Guide](packages/rules/.ai-rules/adapters/q.md) | | Kiro | MCP Server | [Guide](packages/rules/.ai-rules/adapters/kiro.md) | | Windsurf | MCP Server | [Guide](packages/rules/.ai-rules/adapters/windsurf.md) | | Aider | MCP Server | [Guide](packages/rules/.ai-rules/adapters/aider.md) | | OpenCode | MCP Server | [Guide](packages/rules/.ai-rules/adapters/opencode.md) | [All Setup Guides →](docs/supported-tools.md) --- ## How It Works Codingbuddy enforces a quality-driven development cycle: ``` PLAN ACT EVAL ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ Architect │ │Developer │ │ Code Review │ │ designs │───────▶ │implements│───────▶ │ + Parallel │ │ approach │ │ with TDD │ │ Specialists │ └──────────┘ └──────────┘ └──────┬───────┘ │ ┌─────────┴─────────┐ │ │ Critical > 0? Critical = 0 High > 0? High = 0 │ │ ▼ ▼ Back to PLAN Ship with confidence ``` **AUTO mode** runs the full cycle autonomously: ``` AUTO: Implement JWT authentication with refresh tokens → Plans architecture with security requirements → Implements with TDD → Reviews: security, performance, accessibility, code quality → Iterates until production-ready ``` --- ## Impact Telemetry Codingbuddy tracks what its agents do during your session and generates a summary at the end. ### What It Tracks | Event | Description | |-------|-------------| | Mode transitions | PLAN/ACT/EVAL workflow progression | | Agents dispatched | Which specialists were activated and when | | Issues prevented | Problems caught before reaching production | | Checklists generated | Domain-specific quality gates applied | | Context decisions | Architectural decisions persisted across sessions | | Rules matched | Project-specific rules enforced during the session | ### How It Works 1. Every MCP tool call logs impact events to the session 2. Events are categorized by domain (security, accessibility, performance, quality) and severity 3. At session end, `get_session_impact` generates the summary report No configuration needed. Impact telemetry is always on. --- ## Agents 37 specialist agents organized in a 3-tier system. ### Mode Agents (4) Orchestrate the development workflow. | Agent | Role | |-------|------| | Plan Mode | Design architecture and test strategy | | Act Mode | Execute implementation with TDD | | Eval Mode | Multi-specialist code review | | Auto Mode | Autonomous PLAN → ACT → EVAL until quality met | ### Primary Agents (18) Core implementation and review roles. | Agent | Focus | |-------|-------| | Solution Architect | High-level system design | | Technical Planner | Implementation planning with TDD tasks | | Frontend Developer | React/Next.js, Server Components, accessibility | | Backend Developer | Node.js, Python, Go, Java — Clean Architecture | | Mobile Developer | React Native, Flutter, iOS, Android | | Data Engineer | Schema design, migrations, query optimization | | Data Scientist | EDA, statistical modeling, ML, Jupyter | | Systems Developer | Rust, C/C++, FFI, embedded, low-level performance | | Code Reviewer | Multi-dimensional quality assessment | | Test Engineer | TDD cycle, coverage, all test types | | Security Engineer | Auth, encryption, vulnerability remediation | | Software Engineer | General-purpose, any language (fallback) | | DevOps Engineer | Docker, monitoring, deployment | | Platform Engineer | IaC, Kubernetes, multi-cloud, GitOps | | Tooling Engineer | Build tools, project configuration | | Agent Architect | AI agent design and validation | | AI/ML Engineer | LLM integration, RAG, prompt engineering | | UI/UX Designer | Visual hierarchy, interaction patterns, UX laws | ### Specialist Agents (13) Domain experts dispatched in parallel during EVAL. | Agent | Domain | |-------|--------| | Architecture | Layer boundaries, dependency direction, SOLID | | Test Strategy | TDD vs test-after, coverage planning | | Security | OWASP, auth/authz, XSS/CSRF | | Accessibility | WCAG 2.1 AA, ARIA, keyboard navigation | | Performance | Core Web Vitals, bundle size, rendering | | Code Quality | Complexity analysis, DRY, design patterns | | SEO | Metadata, JSON-LD, Open Graph | | i18n | Translation keys, RTL, locale formatting | | Integration | API patterns, OAuth, circuit breakers | | Event Architecture | Event Sourcing, CQRS, Saga, message queues | | Documentation | JSDoc, code comments, API docs | | Observability | OpenTelemetry, tracing, SLI/SLO | | Migration | Strangler Fig, zero-downtime migrations | ### Utility Agents (2) | Agent | Purpose | |-------|---------| | Parallel Orchestrator | Multi-issue parallel execution with file-overlap validation | | Plan Reviewer | Plan quality and feasibility checks | [Full Agent Reference →](packages/rules/.ai-rules/agents/README.md) --- ## Built-in Skills Reusable workflows that enforce consistent development practices. | Skill | Description | |-------|-------------| | `ship` | Run CI checks, create branch, commit, push, and PR | | `retrospective` | Analyze session archives for patterns and improvements | | `test-driven-development` | Red → Green → Refactor cycle enforcement | | `systematic-debugging` | Root cause analysis before proposing fixes | | `security-audit` | OWASP Top 10 review, secrets scanning | | `performance-optimization` | Profiling-first optimization workflow | | `refactoring` | Tidy First principles with test safety | | `brainstorming` | Explore intent and requirements before building | [Full Skills Library →](packages/rules/.ai-rules/skills/README.md) --- ## Configuration Create `codingbuddy.config.json` in your project root: ```json { "language": "en", "verbosity": "compact", "ai": { "defaultModel": "claude-sonnet-4-20250514" } } ``` | Setting | Options | Default | |---------|---------|---------| | `language` | `en`, `ko`, `ja`, `zh`, `es`, `pt-br`, `de`, `fr` | `en` | | `verbosity` | `minimal`, `compact`, `standard`, `detailed` | `compact` | | `ai.defaultModel` | Any Claude model ID | `claude-sonnet-4-*` | [Configuration Reference →](docs/config-schema.md) --- ## Terminal Dashboard (TUI) Real-time visualization of agent activity, task progress, and workflow state. ```bash npx codingbuddy tui ``` Multi-session support, responsive layout, and zero overhead on MCP response times. [TUI Guide →](docs/tui-guide.md) --- ## Documentation | Document | Description | |----------|-------------| | [Getting Started](docs/getting-started.md) | Installation and setup | | [Agent System](packages/rules/.ai-rules/agents/README.md) | Complete agent reference | | [Skills Library](packages/rules/.ai-rules/skills/README.md) | Workflow skills | | [Supported Tools](docs/supported-tools.md) | AI tool integration guides | | [Configuration](docs/config-schema.md) | Config file options | | [Plugin Guide](docs/plugin-guide.md) | Claude Code plugin setup | | [TUI Guide](docs/tui-guide.md) | Terminal dashboard | | [API Reference](docs/api.md) | MCP server capabilities | --- ## Contributing We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License MIT © [Codingbuddy](https://github.com/JeremyDev87/codingbuddy)