@corbat-tech/coco 2.0.0 โ 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +347 -203
- package/dist/cli/index.js +2836 -931
- package/dist/cli/index.js.map +1 -1
- package/dist/index.d.ts +12 -2
- package/dist/index.js +109 -31
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,313 +1,457 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<img src="docs/assets/logo.png" alt="Coco โ autonomous AI coding agent" width="640"/>
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
<br/>
|
|
6
6
|
|
|
7
|
-
[
|
|
8
|
-
[
|
|
9
|
-
[How It Works](#-how-it-works) โข
|
|
10
|
-
[Commands](#-commands) โข
|
|
11
|
-
[Documentation](#-documentation)
|
|
12
|
-
|
|
13
|
-
[](https://www.npmjs.com/package/@corbat-tech/coco)
|
|
14
|
-
[](LICENSE)
|
|
7
|
+
[](https://www.npmjs.com/package/@corbat-tech/coco)
|
|
8
|
+
[](https://nodejs.org/)
|
|
15
9
|
[](https://www.typescriptlang.org/)
|
|
16
|
-
[](LICENSE)
|
|
11
|
+
[](https://github.com/corbat-tech/coco/actions)
|
|
18
12
|
|
|
19
|
-
|
|
13
|
+
<br/>
|
|
20
14
|
|
|
21
|
-
|
|
15
|
+
[Install](#install) ยท [Quick Start](#quick-start) ยท [How It Works](#how-it-works) ยท [Providers](#providers) ยท [Skills](#skills) ยท [Docs](#documentation)
|
|
22
16
|
|
|
23
|
-
|
|
17
|
+
</div>
|
|
24
18
|
|
|
25
|
-
|
|
19
|
+
---
|
|
26
20
|
|
|
27
|
-
## The
|
|
21
|
+
## The one-line pitch
|
|
28
22
|
|
|
29
|
-
|
|
23
|
+
Most AI tools write code and hand it back. If tests fail or security is off โ that's your problem. **Coco runs the loop for you**: write โ test โ measure โ fix, until your code actually hits a quality bar worth shipping.
|
|
30
24
|
|
|
31
|
-
|
|
32
|
-
- โ
Runs your tests
|
|
33
|
-
- ๐ Measures quality across 12 dimensions
|
|
34
|
-
- ๐ Diagnoses what's wrong
|
|
35
|
-
- ๐ง Fixes issues and repeats
|
|
25
|
+
---
|
|
36
26
|
|
|
37
|
-
|
|
27
|
+
## What it looks like
|
|
38
28
|
|
|
39
29
|
```
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
30
|
+
$ coco "Add JWT authentication to the Express API"
|
|
31
|
+
|
|
32
|
+
โ Converging on requirements...
|
|
33
|
+
โ Designing architecture โ 3 tasks planned
|
|
34
|
+
|
|
35
|
+
Task 1/3 JWT middleware
|
|
36
|
+
ยท iter 1 โโ score 58 missing error handling, 0 tests written
|
|
37
|
+
ยท iter 2 โโ score 79 tests added, OWASP issue detected
|
|
38
|
+
ยท iter 3 โโ score 91 โ converged
|
|
39
|
+
|
|
40
|
+
Task 2/3 Auth routes /login ยท /refresh ยท /logout
|
|
41
|
+
ยท iter 1 โโ score 71 coverage 42%, input not validated
|
|
42
|
+
ยท iter 2 โโ score 89 โ converged
|
|
43
|
+
|
|
44
|
+
Task 3/3 Integration tests
|
|
45
|
+
ยท iter 1 โโ score 94 โ converged first try
|
|
46
|
+
|
|
47
|
+
โญโโโโโโโโโโโโโ Quality Report โโโโโโโโโโโโโโฎ
|
|
48
|
+
โ Correctness 96 โโโโโโโโโโโโโโโโ โ
|
|
49
|
+
โ Security 100 โโโโโโโโโโโโโโโโ โ
|
|
50
|
+
โ Test Coverage 88 โโโโโโโโโโโโโโโโ โ
|
|
51
|
+
โ Complexity 91 โโโโโโโโโโโโโโโโ โ
|
|
52
|
+
โ Documentation 84 โโโโโโโโโโโโโโโโ โ
|
|
53
|
+
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
|
|
54
|
+
โ Overall 92 โโโโโโโโโโโโโโโโ โ
|
|
55
|
+
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
|
|
56
|
+
|
|
57
|
+
3 files written ยท 47 tests ยท 88% coverage ยท 0 vulnerabilities
|
|
46
58
|
```
|
|
47
59
|
|
|
48
60
|
---
|
|
49
61
|
|
|
50
|
-
##
|
|
51
|
-
|
|
52
|
-
|
|
|
53
|
-
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
|
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
|
|
62
|
+
## Why Coco
|
|
63
|
+
|
|
64
|
+
| What you usually do | What Coco does |
|
|
65
|
+
|---------------------|----------------|
|
|
66
|
+
| Write code, run tests manually, fix, repeat | Autonomous iterate-until-quality loop |
|
|
67
|
+
| Hope your reviewer catches security issues | OWASP pattern analysis on every iteration |
|
|
68
|
+
| Guess at test coverage | c8/v8 instrumentation, measured per task |
|
|
69
|
+
| One model, one provider, take it or leave it | 12 providers, switch any time |
|
|
70
|
+
| Workflows live in your head or Confluence | Reusable skills committed to the repo |
|
|
71
|
+
|
|
72
|
+
### How Coco compares
|
|
73
|
+
|
|
74
|
+
| | Coco | Aider | Claude Code | Cursor |
|
|
75
|
+
|---|---|---|---|---|
|
|
76
|
+
| Quality convergence loop | โ
| โ | โ | โ |
|
|
77
|
+
| Runs tests + measures coverage | โ
| โ | โ | โ |
|
|
78
|
+
| Provider-agnostic (12 providers) | โ
| โ
| โ Anthropic only | Partial |
|
|
79
|
+
| Works in terminal | โ
| โ
| โ
| โ IDE only |
|
|
80
|
+
| Reusable team workflows (Skills) | โ
| โ | โ
CLAUDE.md | โ |
|
|
81
|
+
| MCP tool integration | โ
| โ | โ
| โ
|
|
|
82
|
+
| Local models (Ollama, LM Studio) | โ
| โ
| โ | Partial |
|
|
83
|
+
| Subscription-based providers | โ
ChatGPT, Kimi Code | โ | โ
Claude Max | โ
|
|
|
60
84
|
|
|
61
85
|
---
|
|
62
86
|
|
|
63
|
-
##
|
|
64
|
-
|
|
65
|
-
### ๐ **Quality Convergence Loop** (COCO Mode)
|
|
66
|
-
|
|
67
|
-
Not just code generation โ **iterative quality improvement**:
|
|
87
|
+
## Install
|
|
68
88
|
|
|
69
|
-
|
|
70
|
-
|:---------:|:-----:|--------|
|
|
71
|
-
| **1** | 52 | Code generated โ 3 tests failing, no error handling |
|
|
72
|
-
| **2** | 71 | Tests fixed, security vulnerability found |
|
|
73
|
-
| **3** | 84 | Security patched, coverage 82% |
|
|
74
|
-
| **4** | **91** | โ
**All green โ quality converged** |
|
|
89
|
+
### Prerequisites
|
|
75
90
|
|
|
76
|
-
|
|
91
|
+
Coco requires **Node.js 22 or higher**. Check your version:
|
|
77
92
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
| Dimension | How It's Measured |
|
|
83
|
-
|-----------|-------------------|
|
|
84
|
-
| Test Coverage | c8/v8 instrumentation |
|
|
85
|
-
| Security | Pattern matching (OWASP) + optional Snyk |
|
|
86
|
-
| Complexity | Cyclomatic complexity (AST) |
|
|
87
|
-
| Duplication | Line-based similarity |
|
|
88
|
-
| Correctness | Test pass rate + build verification |
|
|
89
|
-
| Style | oxlint / eslint / biome |
|
|
90
|
-
| Documentation | JSDoc / Javadoc coverage |
|
|
91
|
-
| + 5 more | Readability, Maintainability, Test Quality, Completeness, Robustness |
|
|
93
|
+
```bash
|
|
94
|
+
node --version # should print v22.x.x or higher
|
|
95
|
+
```
|
|
92
96
|
|
|
93
|
-
|
|
97
|
+
Don't have Node.js? Install it for your platform:
|
|
94
98
|
|
|
95
|
-
|
|
99
|
+
**macOS**
|
|
100
|
+
```bash
|
|
101
|
+
# Homebrew (recommended)
|
|
102
|
+
brew install node
|
|
96
103
|
|
|
97
|
-
|
|
104
|
+
# Or use the official installer: https://nodejs.org
|
|
105
|
+
```
|
|
98
106
|
|
|
107
|
+
**Linux (Debian/Ubuntu)**
|
|
99
108
|
```bash
|
|
100
|
-
|
|
109
|
+
# Via NodeSource (keeps Node up to date)
|
|
110
|
+
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
|
|
111
|
+
sudo apt-get install -y nodejs
|
|
101
112
|
```
|
|
102
113
|
|
|
103
|
-
**
|
|
114
|
+
**Linux (Fedora/RHEL)**
|
|
115
|
+
```bash
|
|
116
|
+
sudo dnf install nodejs
|
|
117
|
+
```
|
|
104
118
|
|
|
105
|
-
|
|
119
|
+
**WSL2 (Windows)**
|
|
106
120
|
|
|
107
|
-
|
|
121
|
+
Coco works great on WSL2. If you don't have WSL2 set up yet:
|
|
108
122
|
|
|
109
|
-
|
|
123
|
+
```powershell
|
|
124
|
+
# In PowerShell (as Administrator)
|
|
125
|
+
wsl --install
|
|
126
|
+
```
|
|
110
127
|
|
|
111
|
-
|
|
112
|
-
- **Coder** โ Code implementation (default)
|
|
113
|
-
- **Tester** โ Test generation and coverage
|
|
114
|
-
- **Reviewer** โ Quality auditing and code review
|
|
115
|
-
- **Optimizer** โ Refactoring and performance
|
|
116
|
-
- **Planner** โ Architecture and task decomposition
|
|
128
|
+
Then open your WSL2 terminal and follow the Linux instructions above.
|
|
117
129
|
|
|
118
|
-
|
|
130
|
+
> **Native Windows is not supported.** Use WSL2 โ it gives you a full Linux environment on Windows with better performance and tool compatibility.
|
|
119
131
|
|
|
120
|
-
|
|
132
|
+
---
|
|
121
133
|
|
|
122
|
-
|
|
123
|
-
|----------|------|--------|
|
|
124
|
-
| **Anthropic** | API key / OAuth | Claude Opus, Sonnet, Haiku |
|
|
125
|
-
| **OpenAI** | API key | GPT-5.3 Codex, GPT-4.1, o4-mini |
|
|
126
|
-
| **Google** | API key / gcloud | Gemini 3, 2.5 Pro/Flash |
|
|
127
|
-
| **Groq** | API key | Llama 4, Mixtral, Gemma |
|
|
128
|
-
| **OpenRouter** | API key | 200+ models (Claude, GPT, Llamaโฆ) |
|
|
129
|
-
| **Mistral AI** | API key | Mistral Large, Codestral |
|
|
130
|
-
| **DeepSeek** | API key | DeepSeek-V3, DeepSeek-R1 |
|
|
131
|
-
| **Together AI** | API key | Llama 4, Qwen, Falcon |
|
|
132
|
-
| **Hugging Face** | API key | Any HF Inference Endpoint |
|
|
133
|
-
| **Ollama** | Local | Any local model |
|
|
134
|
-
| **LM Studio** | Local | Any GGUF model |
|
|
135
|
-
| **Moonshot** | API key | Kimi models |
|
|
134
|
+
### Install Coco
|
|
136
135
|
|
|
137
|
-
|
|
136
|
+
Once Node.js 22+ is ready:
|
|
138
137
|
|
|
139
|
-
|
|
138
|
+
```bash
|
|
139
|
+
# npm
|
|
140
|
+
npm install -g @corbat-tech/coco
|
|
140
141
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
| **Built-in** | Shipped with coco | Everyone |
|
|
144
|
-
| **Global** | `~/.claude/skills/` | Your machine |
|
|
145
|
-
| **Project** | `.coco/skills/` | The repo |
|
|
142
|
+
# pnpm
|
|
143
|
+
pnpm add -g @corbat-tech/coco
|
|
146
144
|
|
|
147
|
-
|
|
145
|
+
# bun
|
|
146
|
+
bun add -g @corbat-tech/coco
|
|
147
|
+
```
|
|
148
148
|
|
|
149
|
-
|
|
149
|
+
Verify the installation:
|
|
150
150
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
- **Full-access mode** โ `/full-access` for auto-approvals (with safety guards)
|
|
155
|
-
- **Self-update** โ Type "update coco" anytime
|
|
156
|
-
- **WSL2 native** โ Runs inside Windows Subsystem for Linux with correct path translation
|
|
151
|
+
```bash
|
|
152
|
+
coco --version
|
|
153
|
+
```
|
|
157
154
|
|
|
158
155
|
---
|
|
159
156
|
|
|
160
|
-
##
|
|
157
|
+
## Quick Start
|
|
161
158
|
|
|
162
159
|
```bash
|
|
163
|
-
#
|
|
164
|
-
|
|
160
|
+
# Set your API key (Anthropic recommended, others work too)
|
|
161
|
+
export ANTHROPIC_API_KEY="sk-ant-..."
|
|
165
162
|
|
|
166
|
-
# Start interactive
|
|
163
|
+
# Start the interactive REPL โ first run guides you through setup
|
|
167
164
|
coco
|
|
168
165
|
|
|
169
|
-
# Or
|
|
170
|
-
coco "
|
|
166
|
+
# Or go straight to a task
|
|
167
|
+
coco "Build a REST API for user management with tests"
|
|
171
168
|
```
|
|
172
169
|
|
|
173
|
-
That's it. Coco walks you through
|
|
170
|
+
That's it. On first launch Coco walks you through choosing a provider and model.
|
|
171
|
+
|
|
172
|
+
**[5-minute tutorial โ](docs/guides/QUICK_START.md)**
|
|
174
173
|
|
|
175
174
|
---
|
|
176
175
|
|
|
177
|
-
##
|
|
176
|
+
## How It Works
|
|
177
|
+
|
|
178
|
+
Coco uses the **COCO methodology** โ four phases, fully automated:
|
|
179
|
+
|
|
180
|
+
```
|
|
181
|
+
CONVERGE ORCHESTRATE COMPLETE OUTPUT
|
|
182
|
+
โโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโ
|
|
183
|
+
โ Understand โ โโโบ โ Design โ โโโบ โ Build with โ โบ โ Generate โ
|
|
184
|
+
โ the task โ โ + backlog โ โ convergence โ โ CI/CD โ
|
|
185
|
+
โโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโ
|
|
186
|
+
โ โ
|
|
187
|
+
โ loopโ score < threshold
|
|
188
|
+
โโโโโโ
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
**The convergence loop** is what sets Coco apart. After writing each task:
|
|
178
192
|
|
|
179
|
-
|
|
193
|
+
1. Runs your test suite
|
|
194
|
+
2. Scores the result across **12 quality dimensions**
|
|
195
|
+
3. Identifies the weakest areas with specific diagnostics
|
|
196
|
+
4. Generates a targeted fix and repeats
|
|
197
|
+
5. Stops when the score meets your threshold (default: **85/100**)
|
|
198
|
+
|
|
199
|
+
**[Architecture deep dive โ](docs/architecture/ARCHITECTURE.md)**
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## 12-Dimension Quality Scoring
|
|
204
|
+
|
|
205
|
+
Not vibes โ real measurements from static analysis and test instrumentation:
|
|
206
|
+
|
|
207
|
+
| Dimension | How it's measured |
|
|
208
|
+
|-----------|-------------------|
|
|
209
|
+
| **Correctness** | Test pass rate + build verification |
|
|
210
|
+
| **Security** | OWASP pattern matching (must be 100 to ship) |
|
|
211
|
+
| **Test Coverage** | c8/v8 line + branch instrumentation |
|
|
212
|
+
| **Complexity** | Cyclomatic complexity via AST |
|
|
213
|
+
| **Duplication** | Line-based similarity detection |
|
|
214
|
+
| **Style** | oxlint / eslint / biome (your config) |
|
|
215
|
+
| **Documentation** | JSDoc / Javadoc coverage |
|
|
216
|
+
| **Readability** | Derived from complexity + naming |
|
|
217
|
+
| **Maintainability** | Maintainability Index (MI) |
|
|
218
|
+
| **Test Quality** | Assertion density, coverage distribution |
|
|
219
|
+
| **Completeness** | Requirements traceability |
|
|
220
|
+
| **Robustness** | Error handling, edge case coverage |
|
|
221
|
+
|
|
222
|
+
Language-specific analyzers for **TypeScript/JavaScript**, **React/TSX**, and **Java**.
|
|
223
|
+
|
|
224
|
+
**[Quality guide โ](docs/guides/QUALITY.md)**
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## Commands
|
|
229
|
+
|
|
230
|
+
Type `/help` inside the REPL to see everything. The most useful ones day-to-day:
|
|
180
231
|
|
|
181
232
|
| Command | What it does |
|
|
182
|
-
|
|
183
|
-
| `/
|
|
184
|
-
| `/
|
|
233
|
+
|---------|--------------|
|
|
234
|
+
| `/coco [on\|off]` | Toggle quality convergence mode (default: on) |
|
|
235
|
+
| `/check` | Run typecheck + lint + tests inline |
|
|
185
236
|
| `/review` | Code review with severity-rated findings |
|
|
186
237
|
| `/diff` | Visual diff with syntax highlighting |
|
|
187
|
-
| `/ship` | Full release
|
|
188
|
-
| `/
|
|
189
|
-
| `/
|
|
190
|
-
| `/
|
|
191
|
-
|
|
192
|
-
|
|
238
|
+
| `/ship` | Full release: review โ test โ lint โ branch โ PR โ merge |
|
|
239
|
+
| `/full-access [on\|off]` | Auto-approve safe tool calls |
|
|
240
|
+
| `/status` | Project status, git info, session stats |
|
|
241
|
+
| `/compact` | Compress context when the conversation grows long |
|
|
242
|
+
|
|
243
|
+
You don't have to use slash commands. Natural language works:
|
|
244
|
+
|
|
245
|
+
```
|
|
246
|
+
"review the auth module" โ /review
|
|
247
|
+
"let's ship this" โ /ship
|
|
248
|
+
"what changed since yesterday?" โ /diff
|
|
249
|
+
"update coco" โ updates to latest version
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
Bilingual: English and Spanish both work out of the box.
|
|
193
253
|
|
|
194
|
-
|
|
254
|
+
**[Full cookbook and examples โ](docs/guides/COOKBOOK.md)**
|
|
195
255
|
|
|
196
|
-
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## Providers
|
|
259
|
+
|
|
260
|
+
Coco is provider-agnostic. Bring your own key or run fully local:
|
|
197
261
|
|
|
198
|
-
|
|
|
199
|
-
|
|
200
|
-
|
|
|
201
|
-
|
|
|
202
|
-
|
|
|
203
|
-
| **
|
|
262
|
+
| Provider | Models | Auth |
|
|
263
|
+
|----------|--------|------|
|
|
264
|
+
| **Anthropic** โญ | Claude Opus, Sonnet, Haiku | API key / OAuth |
|
|
265
|
+
| **OpenAI** | GPT-4.1, o4-mini, Codex | API key / OAuth |
|
|
266
|
+
| **Google** | Gemini 2.5 Pro/Flash | API key / gcloud |
|
|
267
|
+
| **Groq** | Llama 4, Mixtral, Gemma | API key |
|
|
268
|
+
| **OpenRouter** | 200+ models | API key |
|
|
269
|
+
| **Mistral AI** | Mistral Large, Codestral | API key |
|
|
270
|
+
| **DeepSeek** | DeepSeek-V3, DeepSeek-R1 | API key |
|
|
271
|
+
| **Together AI** | Llama 4, Qwen, Falcon | API key |
|
|
272
|
+
| **xAI** | Grok-2, Grok-2-vision | API key |
|
|
273
|
+
| **Cohere** | Command R+ | API key |
|
|
274
|
+
| **Ollama** | Any local model | Local |
|
|
275
|
+
| **LM Studio** | Any GGUF model | Local |
|
|
204
276
|
|
|
205
|
-
|
|
277
|
+
Switch provider mid-session: `coco config set provider groq`
|
|
278
|
+
|
|
279
|
+
**[Provider guide + compatibility matrix โ](docs/guides/PROVIDERS.md)**
|
|
206
280
|
|
|
207
281
|
---
|
|
208
282
|
|
|
209
|
-
##
|
|
283
|
+
## Skills
|
|
210
284
|
|
|
211
|
-
|
|
285
|
+
Skills are reusable workflows committed to your repo. They're discovered automatically โ no registration step.
|
|
212
286
|
|
|
213
|
-
|
|
287
|
+
**Three scopes, one system:**
|
|
214
288
|
|
|
215
289
|
```
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
โ reqs โ โโโบ โ architecture โโโโบโ quality โโโโบโ CI/CD, โ
|
|
220
|
-
โ + spec โ โ + backlog โ โ convergence โ โ docs โ
|
|
221
|
-
โโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโ
|
|
222
|
-
โ โ
|
|
223
|
-
โโโโโโโโโโโโโโโ
|
|
224
|
-
โ Convergence โ
|
|
225
|
-
โ Loop โ
|
|
226
|
-
โโโโโโโโโโโโโโโ
|
|
290
|
+
~/.coco/skills/ # your machine โ personal workflows
|
|
291
|
+
.coco/skills/ # this repo โ shared with the team
|
|
292
|
+
built-in # shipped with coco
|
|
227
293
|
```
|
|
228
294
|
|
|
229
|
-
|
|
230
|
-
2. **Orchestrate** โ Design architecture
|
|
231
|
-
3. **Complete** โ Build with quality iteration
|
|
232
|
-
4. **Output** โ Generate deployment config
|
|
295
|
+
**Using a skill:**
|
|
233
296
|
|
|
297
|
+
```
|
|
298
|
+
/ship # full release pipeline
|
|
299
|
+
/review # code review
|
|
300
|
+
/check # quality gate
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
**Creating a project skill** โ create `.coco/skills/deploy.md`:
|
|
304
|
+
|
|
305
|
+
```markdown
|
|
306
|
+
---
|
|
307
|
+
name: deploy
|
|
308
|
+
description: Deploy to staging and run smoke tests
|
|
234
309
|
---
|
|
235
310
|
|
|
236
|
-
|
|
311
|
+
Run `pnpm build`, then deploy to staging with `./scripts/deploy.sh staging`,
|
|
312
|
+
then hit the health endpoint and verify 200. Report any failures clearly.
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
Now anyone on the team can type `/deploy`.
|
|
316
|
+
|
|
317
|
+
Skills support Markdown, YAML, and JSON. The skills system auto-reloads on change.
|
|
237
318
|
|
|
238
|
-
|
|
239
|
-
- [Quality Analysis Guide](docs/guides/QUALITY.md)
|
|
240
|
-
- [Provider Guide](docs/guides/PROVIDERS.md)
|
|
241
|
-
- [GitHub Actions Integration](docs/guides/GITHUB-ACTIONS.md)
|
|
242
|
-
- [Quick Start Tutorial](docs/guides/QUICK_START.md)
|
|
243
|
-
- [Troubleshooting](docs/guides/TROUBLESHOOTING.md)
|
|
244
|
-
- [API Reference](docs/API.md)
|
|
245
|
-
- [MCP Integration](docs/MCP.md)
|
|
319
|
+
**[Skills cookbook โ](docs/guides/COOKBOOK.md#skills)**
|
|
246
320
|
|
|
247
321
|
---
|
|
248
322
|
|
|
249
|
-
##
|
|
323
|
+
## MCP Integration
|
|
324
|
+
|
|
325
|
+
Connect Coco to any MCP-compatible server โ filesystem, databases, APIs, browser automation:
|
|
250
326
|
|
|
251
327
|
```bash
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
328
|
+
# Add the official filesystem server
|
|
329
|
+
coco mcp add filesystem \
|
|
330
|
+
--command "npx" \
|
|
331
|
+
--args "-y,@modelcontextprotocol/server-filesystem,/home/user"
|
|
332
|
+
|
|
333
|
+
# Add a database server
|
|
334
|
+
coco mcp add postgres \
|
|
335
|
+
--command "npx" \
|
|
336
|
+
--args "-y,@modelcontextprotocol/server-postgres" \
|
|
337
|
+
--env "DATABASE_URL=postgresql://..."
|
|
258
338
|
```
|
|
259
339
|
|
|
260
|
-
|
|
340
|
+
Once connected, MCP tools are registered and available to the agent alongside built-in tools.
|
|
341
|
+
|
|
342
|
+
**[MCP guide โ](docs/MCP.md)**
|
|
343
|
+
|
|
344
|
+
---
|
|
345
|
+
|
|
346
|
+
## Configuration
|
|
347
|
+
|
|
348
|
+
```bash
|
|
349
|
+
# Project config (committed to the repo)
|
|
350
|
+
cat .coco.config.json
|
|
261
351
|
|
|
352
|
+
# CLI config
|
|
353
|
+
coco config list
|
|
354
|
+
coco config set quality.minScore 90
|
|
355
|
+
coco config set provider deepseek
|
|
262
356
|
```
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
357
|
+
|
|
358
|
+
`.coco.config.json` example:
|
|
359
|
+
|
|
360
|
+
```json
|
|
361
|
+
{
|
|
362
|
+
"name": "my-api",
|
|
363
|
+
"language": "typescript",
|
|
364
|
+
"quality": {
|
|
365
|
+
"minScore": 88,
|
|
366
|
+
"maxIterations": 8
|
|
367
|
+
}
|
|
368
|
+
}
|
|
270
369
|
```
|
|
271
370
|
|
|
272
|
-
**
|
|
371
|
+
**[Configuration reference โ](docs/guides/CONFIGURATION.md)**
|
|
273
372
|
|
|
274
373
|
---
|
|
275
374
|
|
|
276
|
-
##
|
|
375
|
+
## Multi-Agent Architecture
|
|
376
|
+
|
|
377
|
+
Six specialized agents route automatically based on the task:
|
|
378
|
+
|
|
379
|
+
- **Researcher** โ codebase exploration, context gathering
|
|
380
|
+
- **Coder** โ implementation (default for most tasks)
|
|
381
|
+
- **Tester** โ test generation and coverage improvement
|
|
382
|
+
- **Reviewer** โ quality audits, security analysis
|
|
383
|
+
- **Optimizer** โ refactoring, performance improvements
|
|
384
|
+
- **Planner** โ architecture, task decomposition
|
|
277
385
|
|
|
278
|
-
|
|
279
|
-
- **Refactoring** โ Improve quality with measurable progress
|
|
280
|
-
- **Test generation** โ Meaningful tests, not boilerplate
|
|
281
|
-
- **Code review** โ 12-dimensional quality feedback
|
|
282
|
-
- **Learning** โ See how quality improves across iterations
|
|
386
|
+
For complex tasks, agents run in parallel where dependencies allow.
|
|
283
387
|
|
|
284
388
|
---
|
|
285
389
|
|
|
286
|
-
##
|
|
390
|
+
## Documentation
|
|
287
391
|
|
|
288
|
-
|
|
392
|
+
| Guide | What's in it |
|
|
393
|
+
|-------|-------------|
|
|
394
|
+
| [Quick Start](docs/guides/QUICK_START.md) | Install, setup, first project |
|
|
395
|
+
| **[Cookbook & Examples](docs/guides/COOKBOOK.md)** | Prompting patterns, skills, MCP, daily workflows |
|
|
396
|
+
| [Configuration](docs/guides/CONFIGURATION.md) | Full config reference |
|
|
397
|
+
| [Providers](docs/guides/PROVIDERS.md) | Provider setup, compatibility, cost table |
|
|
398
|
+
| [Quality Guide](docs/guides/QUALITY.md) | 12-dimension analysis, language support, CI |
|
|
399
|
+
| [GitHub Actions](docs/guides/GITHUB-ACTIONS.md) | CI/CD integration, PR comments |
|
|
400
|
+
| [MCP Integration](docs/MCP.md) | Connecting external tools |
|
|
401
|
+
| [Architecture](docs/architecture/ARCHITECTURE.md) | System design, ADRs |
|
|
402
|
+
| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common issues |
|
|
289
403
|
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
404
|
+
---
|
|
405
|
+
|
|
406
|
+
## Development
|
|
407
|
+
|
|
408
|
+
```bash
|
|
409
|
+
git clone https://github.com/corbat-tech/coco
|
|
410
|
+
cd coco
|
|
411
|
+
pnpm install
|
|
412
|
+
|
|
413
|
+
pnpm dev # run with tsx (hot reload)
|
|
414
|
+
pnpm check # typecheck + lint + test
|
|
415
|
+
pnpm test # 5290 tests
|
|
416
|
+
pnpm format:fix # fix formatting
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
**Stack:** TypeScript ยท Node.js 22 ยท Vitest ยท oxlint ยท oxfmt ยท Zod ยท Commander
|
|
420
|
+
|
|
421
|
+
---
|
|
422
|
+
|
|
423
|
+
## Known Limitations
|
|
424
|
+
|
|
425
|
+
- **CLI only** โ no VS Code extension yet
|
|
426
|
+
- **Convergence takes time** โ expect 2โ5 min per task depending on complexity
|
|
427
|
+
- **Quality depends on the model** โ Claude Opus gives the best results; smaller models score lower
|
|
428
|
+
- **Not yet battle-tested at enterprise scale** โ production use at medium-scale projects, feedback welcome
|
|
294
429
|
|
|
295
430
|
---
|
|
296
431
|
|
|
297
|
-
##
|
|
432
|
+
## Privacy
|
|
433
|
+
|
|
434
|
+
Coco sends your prompts and relevant code context to the LLM provider you configure. Your code is not stored by Coco and is not used to train models โ that is governed by each provider's own data policy:
|
|
435
|
+
|
|
436
|
+
- **Anthropic**: https://www.anthropic.com/privacy
|
|
437
|
+
- **OpenAI**: https://openai.com/policies/privacy-policy
|
|
438
|
+
- **Google Gemini**: https://policies.google.com/privacy
|
|
439
|
+
- **Local models** (Ollama, LM Studio): nothing leaves your machine
|
|
440
|
+
|
|
441
|
+
Coco does not collect telemetry. No usage data is sent to Corbat.
|
|
442
|
+
|
|
443
|
+
---
|
|
298
444
|
|
|
299
|
-
|
|
445
|
+
## Contributing
|
|
300
446
|
|
|
301
|
-
|
|
302
|
-
- ๐ฌ New quality analyzers
|
|
303
|
-
- ๐ Additional LLM providers
|
|
304
|
-
- ๐ Documentation and examples
|
|
447
|
+
Contributions welcome โ especially new quality analyzers and providers.
|
|
305
448
|
|
|
306
|
-
|
|
449
|
+
- Bug reports: [GitHub Issues](https://github.com/corbat-tech/coco/issues)
|
|
450
|
+
- See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow
|
|
307
451
|
|
|
308
452
|
---
|
|
309
453
|
|
|
310
|
-
##
|
|
454
|
+
## License
|
|
311
455
|
|
|
312
456
|
MIT ยฉ [Corbat](https://corbat.tech)
|
|
313
457
|
|
|
@@ -315,8 +459,8 @@ MIT ยฉ [Corbat](https://corbat.tech)
|
|
|
315
459
|
|
|
316
460
|
<div align="center">
|
|
317
461
|
|
|
318
|
-
**
|
|
462
|
+
**Write the requirement. Coco does the rest.** ๐ฅฅ
|
|
319
463
|
|
|
320
|
-
[
|
|
464
|
+
[npm](https://www.npmjs.com/package/@corbat-tech/coco) ยท [GitHub](https://github.com/corbat-tech/coco) ยท [corbat.tech](https://corbat.tech)
|
|
321
465
|
|
|
322
466
|
</div>
|