<p align="center">
  <img src="https://img.shields.io/badge/v1.2.0-stable-blueviolet?style=for-the-badge" alt="Version">
  <img src="https://img.shields.io/badge/TypeScript-5.7-3178c6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript">
  <img src="https://img.shields.io/badge/Node.js-22+-339933?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node.js">
  <img src="https://img.shields.io/badge/License-MIT-f5c542?style=for-the-badge" alt="MIT License">
  <img src="https://img.shields.io/badge/Tests-4350%2B_passing-22c55e?style=for-the-badge" alt="Tests">
</p>

<h1 align="center">🥥 Corbat-Coco</h1>

<p align="center">
  <strong>The open-source coding agent that iterates on your code until it's actually production-ready.</strong>
</p>

<p align="center">
  <em>Generate → Test → Measure → Fix → Repeat — autonomously.</em>
</p>

---

## 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

```bash
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.

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

---

## 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 loop is configurable: target score, max iterations, convergence threshold, security requirements. You control the bar.

### 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-4o, o1, o3 |
| **Google** | API key / gcloud ADC | Gemini Pro, Flash |
| **Ollama** | Local | Any local model |
| **LM Studio** | Local | Any GGUF model |
| **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** — `/coco`, `/plan`, `/build`, `/diff`, `/commit`, `/help`
- **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

```bash
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/        # 6 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](./CONTRIBUTING.md) for guidelines.

---

## About

Corbat-Coco is built by [Corbat](https://corbat.tech), a technology consultancy that believes AI coding tools should be transparent, measurable, and open source.

<p align="center">
  <a href="https://github.com/corbat/corbat-coco">GitHub</a> · <a href="https://corbat.tech">corbat.tech</a>
</p>

<p align="center"><strong>MIT License</strong> · Made by developers who measure before they ship. 🥥</p>
