npm - @corbat-tech/coco - Versions diffs - 2.22.2 → 2.23.1 - Mend

@corbat-tech/coco 2.22.2 → 2.23.1

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.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,378 +1,155 @@
 <div align="center">
-<img src="docs/assets/logo.png" alt="Coco — autonomous AI coding agent" width="640"/>
+<img src="docs/assets/logo.png" alt="Coco - autonomous coding agent" width="560"/>
 <br/>
-[![npm](https://img.shields.io/npm/v/@corbat-tech/coco?style=flat-square&color=a855f7&label=npm)](https://www.npmjs.com/package/@corbat-tech/coco)
-[![Node](https://img.shields.io/badge/Node.js-22+-22c55e?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![npm](https://img.shields.io/npm/v/@corbat-tech/coco?style=flat-square&label=npm)](https://www.npmjs.com/package/@corbat-tech/coco)
+[![Node](https://img.shields.io/badge/Node.js-22%2B-22c55e?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/license-MIT-f59e0b?style=flat-square)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-5738_passing-22c55e?style=flat-square)](https://github.com/corbat-tech/coco/actions)
-<br/>
-[Install](#install) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Providers](#providers) · [Skills](#skills) · [Docs](#documentation)
+[Install](#install) · [Quick Start](#quick-start) · [What Coco Does](#what-coco-does) · [Providers](#providers) · [Documentation](#documentation)
 </div>
 ---
-## The one-line pitch
+## What Is Coco?
-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.
----
+Coco is a CLI coding agent for real projects. It can plan work, edit files, run tools and tests, and iterate until a quality threshold is reached.
-## What it looks like
+Core idea: instead of a single "here is some code" response, Coco runs an implementation loop with validation and fixes.
-```
-$ coco "Add JWT authentication to the Express API"
-  ◆ Converging on requirements...
-  ◆ Designing architecture — 3 tasks planned
-  Task 1/3  JWT middleware
-  ·  iter 1  ──  score 58  missing error handling, 0 tests written
-  ·  iter 2  ──  score 79  tests added, OWASP issue detected
-  ·  iter 3  ──  score 91  ✓ converged
-  Task 2/3  Auth routes  /login · /refresh · /logout
-  ·  iter 1  ──  score 71  coverage 42%, input not validated
-  ·  iter 2  ──  score 89  ✓ converged
-  Task 3/3  Integration tests
-  ·  iter 1  ──  score 94  ✓ converged first try
-  ╭───────────── Quality Report ─────────────╮
-  │  Correctness      96   ████████████████  │
-  │  Security        100   ████████████████  │
-  │  Test Coverage    88   ██████████████░░  │
-  │  Complexity       91   ████████████████  │
-  │  Documentation    84   █████████████░░░  │
-  │  ─────────────────────────────────────  │
-  │  Overall          92   ████████████████  │
-  ╰──────────────────────────────────────────╯
-  3 files written · 47 tests · 88% coverage · 0 vulnerabilities
-```
+## What Coco Does
----
+- Multi-step execution in one run: explore -> implement -> test -> refine.
+- Quality mode with convergence scoring (configurable threshold and max iterations).
+- Native tool use: files, git, shell, search/web, review, diff, build/test, MCP servers.
+- Multi-provider support (API, subscription, and local models).
+- Session-oriented REPL with slash commands, context compaction, and resumable workflows.
-## Why Coco
-| What you usually do | What Coco does |
-|---------------------|----------------|
-| Write code, run tests manually, fix, repeat | Autonomous iterate-until-quality loop |
-| Hope your reviewer catches security issues | OWASP pattern analysis on every iteration |
-| Guess at test coverage | c8/v8 instrumentation, measured per task |
-| One model, one provider, take it or leave it | 12 providers, switch any time |
-| Workflows live in your head or Confluence | Reusable skills committed to the repo |
-### How Coco compares
-| | Coco | Aider | Claude Code | Cursor |
-|---|---|---|---|---|
-| Quality convergence loop | ✅ | ❌ | ❌ | ❌ |
-| Runs tests + measures coverage | ✅ | ❌ | ❌ | ❌ |
-| Provider-agnostic (12 providers) | ✅ | ✅ | ❌ Anthropic only | Partial |
-| Works in terminal | ✅ | ✅ | ✅ | ❌ IDE only |
-| Reusable team workflows (Skills) | ✅ | ❌ | ✅ CLAUDE.md | ❌ |
-| MCP tool integration | ✅ | ❌ | ✅ | ✅ |
-| Local models (Ollama, LM Studio) | ✅ | ✅ | ❌ | Partial |
-| Subscription-based providers | ✅ ChatGPT, Kimi Code | ❌ | ✅ Claude Max | ✅ |
----
+Coco is designed to be useful on medium and large repos, not only toy examples.
 ## Install
 ### Prerequisites
-Coco requires **Node.js 22 or higher**. Check your version:
+- Node.js `22+`
+- macOS or Linux
+- Windows: use WSL2
 ```bash
-node --version   # should print v22.x.x or higher
+node --version
 ```
-Don't have Node.js? Install it for your platform:
-**macOS**
-```bash
-# Homebrew (recommended)
-brew install node
-# Or use the official installer: https://nodejs.org
-```
-**Linux (Debian/Ubuntu)**
-```bash
-# Via NodeSource (keeps Node up to date)
-curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
-sudo apt-get install -y nodejs
-```
-**Linux (Fedora/RHEL)**
-```bash
-sudo dnf install nodejs
-```
-**WSL2 (Windows)**
-Coco works great on WSL2. If you don't have WSL2 set up yet:
-```powershell
-# In PowerShell (as Administrator)
-wsl --install
-```
-Then open your WSL2 terminal and follow the Linux instructions above.
-> **Native Windows is not supported.** Use WSL2 — it gives you a full Linux environment on Windows with better performance and tool compatibility.
----
-### Install Coco
-Once Node.js 22+ is ready:
+### Global install
 ```bash
-# npm
 npm install -g @corbat-tech/coco
-# pnpm
+# or
 pnpm add -g @corbat-tech/coco
-# bun
-bun add -g @corbat-tech/coco
 ```
-Verify the installation:
+Verify:
 ```bash
 coco --version
 ```
----
 ## Quick Start
 ```bash
-# Set your API key (Anthropic recommended, others work too)
-export ANTHROPIC_API_KEY="sk-ant-..."
+# Example with Anthropic
+export ANTHROPIC_API_KEY="..."
-# Start the interactive REPL — first run guides you through setup
+# Start interactive mode
 coco
-# Or go straight to a task
-coco "Build a REST API for user management with tests"
-```
-That's it. On first launch Coco walks you through choosing a provider and model.
-**[5-minute tutorial →](docs/guides/QUICK_START.md)**
----
-## How It Works
-Coco uses the **COCO methodology** — four phases, fully automated:
-```
-  CONVERGE             ORCHESTRATE           COMPLETE             OUTPUT
-┌────────────┐       ┌─────────────┐       ┌──────────────┐    ┌──────────┐
-│ Understand │  ──►  │   Design    │  ──►  │  Build with  │ ►  │ Generate │
-│  the task  │       │ + backlog   │       │  convergence │    │  CI/CD   │
-└────────────┘       └─────────────┘       └──────────────┘    └──────────┘
-                                                 ↑    │
-                                                 │ loop│ score < threshold
-                                                 └────┘
+# Or run a direct task
+coco "Add JWT auth to this API with tests"
 ```
-**The convergence loop** is what sets Coco apart. After writing each task:
-1. Runs your test suite
-2. Scores the result across **12 quality dimensions**
-3. Identifies the weakest areas with specific diagnostics
-4. Generates a targeted fix and repeats
-5. Stops when the score meets your threshold (default: **85/100**)
+On first run, Coco guides provider/model setup.
-**[Architecture deep dive →](docs/architecture/ARCHITECTURE.md)**
+## Typical Workflow
----
-## 12-Dimension Quality Scoring
-Not vibes — real measurements from static analysis and test instrumentation:
-| Dimension | How it's measured |
-|-----------|-------------------|
-| **Correctness** | Test pass rate + build verification |
-| **Security** | OWASP pattern matching (must be 100 to ship) |
-| **Test Coverage** | c8/v8 line + branch instrumentation |
-| **Complexity** | Cyclomatic complexity via AST |
-| **Duplication** | Line-based similarity detection |
-| **Style** | oxlint / eslint / biome (your config) |
-| **Documentation** | JSDoc / Javadoc coverage |
-| **Readability** | Derived from complexity + naming |
-| **Maintainability** | Maintainability Index (MI) |
-| **Test Quality** | Assertion density, coverage distribution |
-| **Completeness** | Requirements traceability |
-| **Robustness** | Error handling, edge case coverage |
-Language-specific analyzers for **TypeScript/JavaScript**, **React/TSX**, and **Java**.
-**[Quality guide →](docs/guides/QUALITY.md)**
----
-## Commands
-Type `/help` inside the REPL to see everything. The most useful ones day-to-day:
-| Command | What it does |
-|---------|--------------|
-| `/quality [on\|off]` | Toggle quality convergence mode (default: on) |
-| `/check` | Run typecheck + lint + tests inline |
-| `/review` | Code review with severity-rated findings |
-| `/diff` | Visual diff with syntax highlighting |
-| `/ship` | Full release: review → test → lint → branch → PR → merge |
-| `/full-access [on\|off]` | Auto-approve safe tool calls |
-| `/permissions` | Show trust status and manage tool allowlist |
-| `/permissions allow-commits` | Auto-approve git commits for this project |
-| `/status` | Project status, git info, session stats |
-| `/compact` | Compress context when the conversation grows long |
-| `/copy [N]` or `/cp [N]` | Copy code block #N to clipboard (omit N for last block) |
-| `/image [prompt]` | Paste clipboard image and send to agent with optional prompt |
+1. You give a task.
+2. Coco proposes or derives a plan.
+3. Coco edits code and runs tools/tests.
+4. In quality mode, Coco scores output and iterates on weak points.
+5. Coco returns summary + diffs/results.
-**Keyboard shortcuts:**
+Quality mode is configurable and can be turned on/off per session.
-| Key | What it does |
-|-----|--------------|
-| `Option+C` (macOS) / `Alt+C` (Linux) | Copy last rendered code block to clipboard instantly |
-| `Ctrl+V` | Paste clipboard image — accumulates multiple images before Enter |
-| `Tab` | Accept ghost-text completion for slash commands |
-| `↑` / `↓` | Navigate history / completion menu |
+## Commands (REPL)
-You don't have to use slash commands. Natural language works:
-```
-"review the auth module"          →  /review
-"let's ship this"                 →  /ship
-"what changed since yesterday?"   →  /diff
-"update coco"                     →  updates to latest version
-```
+Common commands:
-Bilingual: English and Spanish both work out of the box.
+- `/help` show available commands and skills.
+- `/provider` switch provider.
+- `/model` switch model.
+- `/quality [on|off]` toggle convergence mode.
+- `/check` run checks in project context.
+- `/review` run code review workflow.
+- `/diff` inspect current changes.
+- `/ship` run release-oriented workflow.
+- `/permissions` inspect/update tool trust.
+- `/compact` compact session context.
-**[Full cookbook and examples →](docs/guides/COOKBOOK.md)**
----
+Natural language requests are supported too; commands are optional.
 ## Providers
-Coco is provider-agnostic. Bring your own key or run fully local:
-| Provider | Models | Auth |
-|----------|--------|------|
-| **Anthropic** ⭐ | Claude Opus, Sonnet, Haiku | API key / OAuth |
-| **OpenAI** | GPT-4.1, o4-mini, Codex | API key / OAuth |
-| **Google** | Gemini 2.5 Pro/Flash | API key / gcloud |
-| **Groq** | Llama 4, Mixtral, Gemma | API key |
-| **OpenRouter** | 200+ models | API key |
-| **Mistral AI** | Mistral Large, Codestral | API key |
-| **DeepSeek** | DeepSeek-V3, DeepSeek-R1 | API key |
-| **Together AI** | Llama 4, Qwen, Falcon | API key |
-| **xAI** | Grok-2, Grok-2-vision | API key |
-| **Cohere** | Command R+ | API key |
-| **Ollama** | Any local model | Local |
-| **LM Studio** | Any GGUF model | Local |
-Switch provider mid-session: `coco config set provider groq`
-**[Provider guide + compatibility matrix →](docs/guides/PROVIDERS.md)**
----
-## Skills
-Skills are reusable workflows committed to your repo. They're discovered automatically — no registration step.
-**Three scopes, one system:**
-```
-~/.coco/skills/            # your machine — personal workflows
-.coco/skills/              # this repo — shared with the team
-built-in                   # shipped with coco
-```
-**Using a skill:**
+Coco currently supports these provider IDs:
-```
-/ship              # full release pipeline
-/review            # code review
-/check             # quality gate
-```
-**Creating a project skill** — create `.coco/skills/deploy.md`:
-```markdown
----
-name: deploy
-description: Deploy to staging and run smoke tests
----
-Run `pnpm build`, then deploy to staging with `./scripts/deploy.sh staging`,
-then hit the health endpoint and verify 200. Report any failures clearly.
-```
+- `anthropic`
+- `openai`
+- `copilot`
+- `gemini`
+- `kimi`
+- `kimi-code`
+- `groq`
+- `openrouter`
+- `mistral`
+- `deepseek`
+- `together`
+- `huggingface`
+- `qwen`
+- `ollama` (local)
+- `lmstudio` (local)
-Now anyone on the team can type `/deploy`.
+Notes:
-Skills support Markdown, YAML, and JSON. The skills system auto-reloads on change.
+- `openai` supports API-key mode and OAuth flow (mapped internally when needed).
+- `copilot` and subscription-backed providers rely on their own auth flow.
+- Local providers run through OpenAI-compatible endpoints.
-**[Skills cookbook →](docs/guides/COOKBOOK.md#skills)**
+For setup details and model matrix:
----
+- [Provider Guide](docs/guides/PROVIDERS.md)
-## MCP Integration
+## Skills and MCP
-Connect Coco to any MCP-compatible server — filesystem, databases, APIs, browser automation:
+Coco supports:
-```bash
-# Add the official filesystem server
-coco mcp add filesystem \
-  --command "npx" \
-  --args "-y,@modelcontextprotocol/server-filesystem,/home/user"
-# Add a database server
-coco mcp add postgres \
-  --command "npx" \
-  --args "-y,@modelcontextprotocol/server-postgres" \
-  --env "DATABASE_URL=postgresql://..."
-```
+- Built-in skills (for example `/review`, `/ship`, `/open`, `/diff`).
+- Project/user skills loaded from skill files.
+- MCP servers for external tools and systems.
-Once connected, MCP tools are registered and available to the agent alongside built-in tools.
+References:
-**[MCP guide →](docs/MCP.md)**
----
+- [MCP Guide](docs/MCP.md)
+- [Cookbook](docs/guides/COOKBOOK.md)
 ## Configuration
-```bash
-# Project config (committed to the repo)
-cat .coco.config.json
-# CLI config
-coco config list
-coco config set quality.minScore 90
-coco config set provider deepseek
-```
+Project-level config in `.coco.config.json` and CLI-level config via `coco config`.
-`.coco.config.json` example:
+Example:
 ```json
 {
-  "name": "my-api",
+  "name": "my-service",
   "language": "typescript",
   "quality": {
     "minScore": 88,
@@ -381,40 +158,19 @@ coco config set provider deepseek
 }
 ```
-**[Configuration reference →](docs/guides/CONFIGURATION.md)**
----
-## Multi-Agent Architecture
-Six specialized agents route automatically based on the task:
-- **Researcher** — codebase exploration, context gathering
-- **Coder** — implementation (default for most tasks)
-- **Tester** — test generation and coverage improvement
-- **Reviewer** — quality audits, security analysis
-- **Optimizer** — refactoring, performance improvements
-- **Planner** — architecture, task decomposition
+See:
-For complex tasks, agents run in parallel where dependencies allow.
----
+- [Configuration Guide](docs/guides/CONFIGURATION.md)
 ## Documentation
-| Guide | What's in it |
-|-------|-------------|
-| [Quick Start](docs/guides/QUICK_START.md) | Install, setup, first project |
-| **[Cookbook & Examples](docs/guides/COOKBOOK.md)** | Prompting patterns, skills, MCP, daily workflows |
-| [Configuration](docs/guides/CONFIGURATION.md) | Full config reference |
-| [Providers](docs/guides/PROVIDERS.md) | Provider setup, compatibility, cost table |
-| [Quality Guide](docs/guides/QUALITY.md) | 12-dimension analysis, language support, CI |
-| [GitHub Actions](docs/guides/GITHUB-ACTIONS.md) | CI/CD integration, PR comments |
-| [MCP Integration](docs/MCP.md) | Connecting external tools |
-| [Architecture](docs/architecture/ARCHITECTURE.md) | System design, ADRs |
-| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common issues |
----
+- [Quick Start](docs/guides/QUICK_START.md)
+- [Cookbook](docs/guides/COOKBOOK.md)
+- [Quality Guide](docs/guides/QUALITY.md)
+- [Providers](docs/guides/PROVIDERS.md)
+- [Architecture](docs/architecture/ARCHITECTURE.md)
+- [Troubleshooting](docs/guides/TROUBLESHOOTING.md)
+- [Release Workflow](docs/RELEASE_WORKFLOW.md)
 ## Development
@@ -423,57 +179,39 @@ git clone https://github.com/corbat-tech/coco
 cd coco
 pnpm install
-pnpm dev          # run with tsx (hot reload)
-pnpm check        # typecheck + lint + test
-pnpm test         # 5604 tests
-pnpm format:fix   # fix formatting
+pnpm build
+pnpm test
+pnpm check
 ```
-**Stack:** TypeScript · Node.js 22 · Vitest · oxlint · oxfmt · Zod · Commander
+Tech stack:
----
-## Known Limitations
+- TypeScript (ESM)
+- Vitest
+- oxlint / oxfmt
+- Zod
+- Commander
-- **CLI only** — no VS Code extension yet
-- **Convergence takes time** — expect 2–5 min per task depending on complexity
-- **Quality depends on the model** — Claude Opus gives the best results; smaller models score lower
-- **Not yet battle-tested at enterprise scale** — production use at medium-scale projects, feedback welcome
+## Current Scope and Limitations
----
+- CLI-first product; VS Code extension source is in `vscode-extension/`.
+- Quality scores depend on project testability and model/tool quality.
+- Provider behavior can vary by endpoint/model generation.
+- Some advanced flows require external tooling (git, CI, MCP servers) to be installed/configured.
 ## Privacy
-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:
+Coco sends prompts and selected context to the configured provider.
-- **Anthropic**: https://www.anthropic.com/privacy
-- **OpenAI**: https://openai.com/policies/privacy-policy
-- **Google Gemini**: https://policies.google.com/privacy
-- **Local models** (Ollama, LM Studio): nothing leaves your machine
-Coco does not collect telemetry. No usage data is sent to Corbat.
----
+- Coco itself does not claim ownership of your code.
+- Provider-side data handling depends on each provider policy.
+- Local providers (`ollama`, `lmstudio`) keep inference on your machine.
 ## Contributing
-Contributions welcome — especially new quality analyzers and providers.
-- Bug reports: [GitHub Issues](https://github.com/corbat-tech/coco/issues)
-- See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow
----
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- Issues and proposals: [GitHub Issues](https://github.com/corbat-tech/coco/issues)
 ## License
-MIT © [Corbat](https://corbat.tech)
----
-<div align="center">
-**Write the requirement. Coco does the rest.** 🥥
-[npm](https://www.npmjs.com/package/@corbat-tech/coco) · [GitHub](https://github.com/corbat-tech/coco) · [corbat.tech](https://corbat.tech)
-</div>
+MIT © Corbat