🥥 Coco

The AI coding agent that actually delivers production-ready code

Features • Quick Start • How It Works • Commands • Documentation

---

The Problem

Most AI coding tools generate code and walk away. If tests fail, types don't match, or security issues creep in — that's on you.

The Solution

Coco doesn't just generate code. It iterates until it's right.

After writing code, Coco automatically:

• ✅ Runs your tests
• 📊 Measures quality across 12 dimensions
• 🔍 Diagnoses what's wrong
• 🔧 Fixes issues and repeats

Until your code hits production-quality standards you define.

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ Generate │ ──► │   Test   │ ──► │ Measure  │ ──► │   Fix    │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                                                         │
                                             Score < 85? │ ──► Loop
                                             Score ≥ 85? │ ──► Done ✅

---

✨ Features

🔄 Quality Convergence Loop (COCO Mode)

Not just code generation — iterative quality improvement:

Iteration	Score	Status
1	52	Code generated — 3 tests failing, no error handling
2	71	Tests fixed, security vulnerability found
3	84	Security patched, coverage 82%
4	91	✅ All green — quality converged

Enable with /coco — now on by default for better results

📊 12-Dimension Quality Scoring

Real metrics, not guesses:

Dimension	How It's Measured
Test Coverage	c8/v8 instrumentation
Security	Pattern matching + optional Snyk
Complexity	Cyclomatic complexity (AST)
Duplication	Line-based similarity
Correctness	Test pass rate + build verification
Style	oxlint / eslint / biome
Documentation	JSDoc coverage
+ 5 more	Readability, Maintainability, Test Quality, Completeness, Robustness

🚀 Full Release Pipeline

Ship with confidence using /ship:

/ship                          # Complete 10-step pipeline

Pipeline: Preflight → Review → Tests → Lint → Branch → Version → Commit → PR → CI → Merge

Each step is interactive — press Ctrl+C anytime to safely cancel.

🤖 Multi-Agent Architecture

Six specialized agents with automatic routing:

• Researcher — Codebase exploration and analysis
• Coder — Code implementation (default)
• Tester — Test generation and coverage
• Reviewer — Quality auditing and code review
• Optimizer — Refactoring and performance
• Planner — Architecture and task decomposition

🌐 Multi-Provider Support

Bring your own API key:

Provider	Auth	Models
Anthropic	API key / OAuth	Claude Opus, Sonnet, Haiku
OpenAI	API key	GPT-5.3 Codex, GPT-4.1, o4-mini
Google	API key / gcloud	Gemini 3, 2.5 Pro/Flash
Ollama	Local	Any local model
LM Studio	Local	Any GGUF model
Moonshot	API key	Kimi models

⚡ Modern Terminal UX

• Ghost-text completion — Tab to accept suggestions
• Image paste — Ctrl+V to paste screenshots
• Intent recognition — Natural language → commands
• Full-access mode — /full-access for auto-approvals (with safety guards)
• Self-update — Type "update coco" anytime

---

🚀 Quick Start

# Install globally
npm install -g @corbat-tech/coco

# Start interactive mode
coco

# Or use directly
coco "Add user authentication with tests"

That's it. Coco walks you through provider setup on first launch.

---

💬 Commands

Slash Commands

Command	What it does
/help	Show available commands
/status	Project status, git info, session stats
/review	Code review with severity-rated findings
/diff	Visual diff with syntax highlighting
/ship	Full release pipeline (review → test → PR → merge)
/coco [on|off]	Toggle quality mode (default: ON)
/full-access [on|off]	Auto-approve safe commands
/compact	Reduce context when conversation grows
/clear	Clear conversation history

Natural Language

You don't need slash commands. Just talk:

You say	Coco does
"review the code"	Runs /review
"let's ship it"	Runs /ship
"show me the changes"	Runs /diff
"update coco"	Runs /update-coco

Bilingual support (English/Spanish).

---

🎯 How It Works

COCO Methodology

Four phases for production-ready output:

 CONVERGE          ORCHESTRATE         COMPLETE            OUTPUT
┌──────────┐     ┌──────────────┐   ┌──────────────┐   ┌──────────┐
│ Gather   │     │ Design       │   │ Execute with │   │ Generate │
│ reqs     │ ──► │ architecture │──►│ quality      │──►│ CI/CD,   │
│ + spec   │     │ + backlog    │   │ convergence  │   │ docs     │
└──────────┘     └──────────────┘   └──────────────┘   └──────────┘
                                         ↑    ↓
                                    ┌─────────────┐
                                    │ Convergence │
                                    │    Loop     │
                                    └─────────────┘

1. Converge — Understand requirements
2. Orchestrate — Design architecture
3. Complete — Build with quality iteration
4. Output — Generate deployment config

---

📖 Documentation

• Configuration Guide
• Quick Start Tutorial
• Troubleshooting
• API Reference
• MCP Integration

---

🧑‍💻 Development

git clone https://github.com/corbat/corbat-coco
cd corbat-coco
pnpm install
pnpm dev          # Run in dev mode
pnpm test         # 4,350+ tests
pnpm check        # Typecheck + lint + test

Project Structure

src/
├── agents/           # Multi-agent coordination
├── cli/              # REPL + commands
├── phases/           # COCO phases
├── quality/          # 12-dimension scoring
├── providers/        # LLM provider integrations
└── tools/            # File ops, git, tests, etc.

Stack: TypeScript + Node.js 22 + Vitest + oxlint/oxfmt + Zod

---

🎓 Use Cases

• Feature development — Get tested, reviewed code
• Refactoring — Improve quality with measurable progress
• Test generation — Meaningful tests, not boilerplate
• Code review — 12-dimensional quality feedback
• Learning — See how quality improves across iterations

---

⚠️ Known Limitations

We'd rather you know upfront:

• TypeScript/JavaScript first — Other languages have basic support
• CLI-only — No IDE extension yet (VS Code planned)
• Iteration takes time — Convergence adds 2-5 min per task
• LLM-dependent — Quality depends on your model choice
• Early stage — Not yet battle-tested at enterprise scale

---

🤝 Contributing

Contributions welcome:

• 🐛 Bug reports and feature requests
• 🔬 New quality analyzers
• 🔌 Additional LLM providers
• 📚 Documentation and examples

See CONTRIBUTING.md.

---

📄 License

MIT © Corbat

---

Built by developers who measure before they ship 🥥

GitHub · corbat.tech · npm