<p align="center"> <a href="README.md">English</a> | <a href="README.ko.md">한국어</a> | <a href="README.zh-CN.md">中文</a> | <a href="README.ja.md">日本語</a> | <a href="README.es.md">Español</a> </p>

Codingbuddy

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

# 1. Install
npm install -g codingbuddy

# 2. Initialize your project
npx codingbuddy init

# 3. Add to your AI tool's MCP config

{
  "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:

# 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 for details.

Full Getting Started Guide →

---

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
Cursor	MCP Server	Guide
GitHub Copilot / Codex	MCP Server	Guide
Antigravity (Gemini)	MCP Server	Guide
Amazon Q	MCP Server	Guide
Kiro	MCP Server	Guide
Windsurf	MCP Server	Guide
Aider	MCP Server	Guide
OpenCode	MCP Server	Guide

All Setup Guides →

---

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 →

---

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 →

---

Configuration

Create codingbuddy.config.json in your project root:

{
  "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 →

---

Terminal Dashboard (TUI)

Real-time visualization of agent activity, task progress, and workflow state.

npx codingbuddy tui

Multi-session support, responsive layout, and zero overhead on MCP response times.

TUI Guide →

---

Documentation

Document	Description
Getting Started	Installation and setup
Agent System	Complete agent reference
Skills Library	Workflow skills
Supported Tools	AI tool integration guides
Configuration	Config file options
Plugin Guide	Claude Code plugin setup
TUI Guide	Terminal dashboard
API Reference	MCP server capabilities

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT © Codingbuddy