Why Coco?

Most AI coding tools generate code and hand it to you. If something breaks — tests fail, types don't match, a security issue slips in — that's your problem.

Coco takes a different approach. After generating code, it runs your tests, measures quality across 12 dimensions, diagnoses what's wrong, and fixes it — in a loop, autonomously — until the code actually meets a quality bar you define.

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

This is the Quality Convergence Loop — Coco's core differentiator.

Quick Start

npm install -g @corbat-tech/coco
coco                        # Opens interactive REPL — guided setup on first run

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

# Or use it directly:
coco "Add a REST API endpoint for user authentication with tests"

What You Can Do

Coco works from the interactive REPL (coco). You can use slash commands or just talk naturally — Coco understands both.

Slash Commands

| Command | What it does | Example | |---------|-------------|---------| | /help | Show available commands and usage | /help review | | /status | Project status, git info, session stats | /status | | /review | Code review with severity-rated findings | /review --base main | | /diff | Visual diff with syntax highlighting | /diff --staged | | /ship | Full release pipeline: review → test → lint → branch → version → commit → PR → CI → merge | /ship --minor | | /compact | Reduce context when conversation gets long | /compact | | /clear | Clear conversation history | /clear |

Natural Language

You don't need to memorize commands. Just describe what you want:

| What you say | What happens | |-------------|-------------| | "review the code" / "revisa el código" | Runs /review | | "let's ship it" / "publica los cambios" | Runs /ship | | "how are we doing?" / "cómo va?" | Runs /status | | "create a PR" / "crea un pull request" | Runs /ship | | "show me the diff" / "muéstrame los cambios" | Runs /diff | | "help" / "ayuda" | Runs /help |

/ship — Release Pipeline

The most powerful command. Orchestrates the entire release flow in one step:

/ship                          # Full pipeline (10 steps)
/ship --skip-tests             # Skip test step
/ship --draft                  # Create draft PR
/ship --patch                  # Force patch version bump
/ship --minor                  # Force minor version bump
/ship --major                  # Force major version bump
/ship --no-version             # Skip version bumping
/ship -m "feat: add auth"     # Pre-set commit message

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

Each step is interactive — Coco asks before proceeding when decisions are needed. Press Ctrl+C at any point to cancel safely.

What Coco Does Well

Quality Convergence Loop

Coco doesn't just generate code — it iterates until quality converges:

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

The quality bar is yours to set:

coco build --min-quality 90          # Per-run override
coco config set quality.minScore 90  # Persist in project config

Default is 85 (senior-level). You can also configure max iterations, convergence threshold, coverage targets, and security requirements — see coco config init.

12-Dimension Quality Scoring

Every iteration measures your code across 12 dimensions using real static analysis:

| Dimension | How it's measured | |-----------|-------------------| | Test Coverage | c8/v8 instrumentation | | Security | Pattern matching + optional Snyk | | Complexity | Cyclomatic complexity via AST parsing | | Duplication | Line-based similarity detection | | Correctness | Test pass rate + build verification | | Style | oxlint / eslint / biome integration | | Documentation | JSDoc coverage analysis | | Readability | AST: naming quality, function length, nesting | | Maintainability | AST: file size, coupling, function count | | Test Quality | Assertion density, edge case coverage | | Completeness | Export density + test file coverage | | Robustness | Error handling pattern detection |

Transparency note: 7 dimensions use instrumented measurements. 5 use heuristic-based static analysis. We label which is which — no black boxes.

Multi-Provider Support

Bring your own API keys. Coco works with:

| Provider | Auth | Models | |----------|------|--------| | Anthropic | API key / OAuth PKCE | Claude Opus, Sonnet, Haiku | | OpenAI | API key | GPT-5.3 Codex, GPT-4.1, o4-mini | | Google | API key / gcloud ADC | Gemini 3, 2.5 Pro/Flash | | Ollama | Local | Any local model (8-24GB RAM) | | LM Studio | Local | Any GGUF model (8-32GB RAM) | | Moonshot | API key | Kimi models |

Multi-Agent Architecture

Six specialized agents with weighted-scoring routing:

• Researcher — Explores, analyzes, maps the codebase
• Coder — Writes and edits code (default route)
• Tester — Generates tests, improves coverage
• Reviewer — Code review, quality auditing
• Optimizer — Refactoring and performance
• Planner — Architecture design, task decomposition

Coco picks the right agent for each task automatically. When confidence is low, it defaults to the coder — no guessing games.

Interactive REPL

A terminal-first experience with:

• Ghost-text completion — Tab to accept inline suggestions
• Slash commands — /ship, /review, /diff, /status, /help, /compact, /clear
• Image paste — Ctrl+V to paste screenshots for visual context
• Intent recognition — Natural language mapped to commands
• Context management — Automatic compaction when context grows large

Production Hardening

• Error recovery with typed error strategies and exponential backoff
• Checkpoint/Resume — Ctrl+C saves state, coco resume picks up where you left off
• AST validation — Syntax-checks generated code before saving
• Convergence analysis — Detects oscillation, diminishing returns, and stuck patterns
• Path sandboxing — Tools can only access files within the project

COCO Methodology

Four phases, each with a dedicated executor:

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

1. Converge — Understand what needs to be built. Gather requirements, produce a spec.
2. Orchestrate — Design the architecture, decompose into a task backlog.
3. Complete — Execute each task with the quality convergence loop.
4. Output — Generate CI/CD pipelines, documentation, and deployment config.

Use Cases

Coco is designed for developers who want AI assistance with accountability:

• Feature development — Describe what you want, get tested and reviewed code
• Vibe coding — Explore ideas interactively; Coco handles the quality checks
• Refactoring — Point at code and say "make this better" — Coco iterates until metrics improve
• Test generation — Improve coverage with meaningful tests, not boilerplate
• Code review — Get multi-dimensional quality feedback on existing code
• Learning — See how code quality improves across iterations

Development

git clone https://github.com/corbat/corbat-coco
cd corbat-coco
pnpm install
pnpm dev          # Run in dev mode (tsx)
pnpm test         # 4,350+ tests via Vitest
pnpm check        # typecheck + lint + test
pnpm build        # Production build (tsup)

Project Structure

src/
├── agents/           # Multi-agent coordination + weighted routing
├── cli/              # REPL, commands, input handling, output rendering
├── orchestrator/     # Phase coordinator + state recovery
├── phases/           # COCO phases (converge/orchestrate/complete/output)
├── quality/          # 12 quality analyzers + convergence engine
├── providers/        # 7 LLM providers + OAuth flows
├── tools/            # 20+ tool implementations
├── hooks/            # Lifecycle hooks (safety, lint, format, audit)
├── mcp/              # MCP server for external integration
└── config/           # Zod-validated configuration system

Technology Stack

| Component | Technology | |-----------|-----------| | Language | TypeScript (ESM, strict mode) | | Runtime | Node.js 22+ | | Testing | Vitest (4,350+ tests) | | Linting | oxlint | | Formatting | oxfmt | | Build | tsup | | Schema validation | Zod |

Known Limitations

We'd rather you know upfront:

• TypeScript/JavaScript first — Other languages have basic support but fewer analyzers
• CLI-only — No IDE extension yet (VS Code integration is planned)
• Iteration takes time — The convergence loop adds 2-5 minutes per task. For quick one-line fixes, a simpler tool may be faster
• Heuristic analyzers — 5 of 12 quality dimensions use pattern-based heuristics, not deep semantic analysis
• LLM-dependent — Output quality depends on the model you connect. Larger models produce better results
• Early stage — Actively developed. Not yet battle-tested at large enterprise scale

Contributing

We welcome contributions of all kinds:

• Bug reports and feature requests
• New quality analyzers
• Additional LLM provider integrations
• Documentation and examples
• Real-world usage feedback

See CONTRIBUTING.md for guidelines.

About

Corbat-Coco is built by Corbat, a technology consultancy that believes AI coding tools should be transparent, measurable, and open source.