@corbat-tech/coco
Advanced tools
Autonomous Coding Agent with Self-Review, Quality Convergence, and Production-Ready Output
Coco is an open-source CLI coding agent and reusable agent runtime for real-world automation. It plans work, edits files, runs tools/tests, and iterates until quality checks pass. Underneath the CLI, Coco exposes a runtime for building custom agents with providers, tools, permissions, sessions, events, and workflows.
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.
Core idea: instead of a single "here is some code" response, Coco runs an implementation loop with validation and fixes.
Best fit:
Coco is built for two related jobs:
That runtime boundary is intentionally practical: provider selection, model turns, tool registration, permission policy, runtime sessions, event logs, workflow metadata, and replay hooks live behind reusable APIs. The CLI is the first product built on that foundation, not the only surface it can support.
coco "/plan add validation for the provider config parser"
# Coco inspects the repo with read-only tools and returns a plan.
coco "implement the plan and run the relevant tests"
# Coco edits files, runs checks, reviews failures, and summarizes the diff.
Typical final output includes changed files, checks run, risks, and next steps. For runtime embedding, see the web assistant and RAG examples below.
Use Coco as a coding agent that can inspect an existing repo, plan changes, edit files, run checks, review diffs, and iterate toward a passing result.
Use Coco Runtime as a base for custom agents: internal assistants, support copilots, operations workflows, sales/product assistants, documentation agents, or client-specific automation. These products can use Coco's runtime without exposing shell, filesystem, git, or publishing tools unless you explicitly register them.
Coding Agent
Multi-provider Runtime
Reliability And Safety
Extensibility
Coco is designed to be useful on medium and large repos, not only toy examples.
22+node --version
npm install -g @corbat-tech/coco
# or
pnpm add -g @corbat-tech/coco
Verify:
coco --version
# Example with Anthropic
export ANTHROPIC_API_KEY="..."
# Start interactive mode
coco
# Or run a direct task
coco "Add JWT auth to this API with tests"
On first run, Coco guides provider/model setup.
Quality mode is configurable and can be turned on/off per session.
Coco's CLI runs on a reusable agent runtime that wires providers, tools, permissions, sessions, event logs, and workflow metadata behind a stable internal boundary. This keeps the programming CLI as the main product while making the same foundation reusable for future client-specific agents.
import { createAgentRuntime, ToolRegistry } from "@corbat-tech/coco";
Runtime consumers can create their own backend, register only the tools they trust, and use Coco for model/provider orchestration, session state, permissions, event logging, and workflow execution.
Subpath imports are available for embedders:
import { createAgentRuntime } from "@corbat-tech/coco/runtime";
import { createSupportRagToolRegistry } from "@corbat-tech/coco/tools";
import { supportRagAssistantPreset } from "@corbat-tech/coco/presets";
Coco does not replace your business systems. It gives you a reusable agent layer that connects models, tools, permissions, sessions, guardrails, and logs in the same way across channels.
For example, in a RAG assistant:
Google Drive / Notion / PDFs / website docs
-> your retriever or vector database
-> Coco Runtime
-> selected model
-> answer with sources, policy, session, and event logs
The retriever still owns document indexing and search. Coco standardizes how the agent uses that search safely: answer from approved knowledge, cite sources, say "I don't know" when retrieval is weak, avoid dangerous tools, and record what happened. The same runtime pattern can then be reused for a website widget, WhatsApp assistant, customer-support draft flow, appointment assistant, or internal operations agent.
| Surface | Status | Notes |
|---|---|---|
| Coco CLI | Beta | Main product surface, used for coding-agent workflows. |
| Runtime APIs | Beta | Exported from @corbat-tech/coco; package split is planned later. |
| Agent presets | Experimental | Safe defaults for public web, RAG, sales, support, appointments, internal ops, and coding. |
| Adapters | Experimental | HTTP, streaming HTTP, and webhook-style adapter shapes. |
For a website such as corbat.tech, the web app should own authentication, users, tenants, UI, and HTTP streaming. Coco Runtime should sit behind that app and own provider selection, model turns, session state, permission checks, tool registration, and event logs.
The recommended pattern is:
Do not reuse Coco's full coding-agent tool registry in a public web assistant. Shell access, arbitrary filesystem operations, git writes, deployment, package publishing, secrets, and private customer data should stay unavailable unless a product-specific backend explicitly gates them.
See examples/web-assistant-runtime for a concrete embedding sketch.
COCO_PROVIDER_RESILIENCE=0).score, iteration usage, tool success/failure, repeated-output suppression).tool_use without reconstructed tool calls, empty max_tokens turns, short planning-only replies) before giving control back.continue prompts.agent.enableAutoSwitchProvider (default: false)./plan cannot drift into write-capable tools unless you explicitly disable agent.planModeStrict./doctor provides a read-only local diagnostics pass for project access, config parsing, provider auth, hooks, and tool registry health.pnpm check:release (typecheck + lint + stable provider/agent suites).Common commands:
/help show available commands and skills./provider switch provider./model switch model./thinking [off|auto|low|medium|high|<tokens>] control the reasoning/thinking budget (claude-4+, o3/o4-mini, gpt-5+, gemini-2.5+)./quality [on|off] toggle convergence mode./check run checks in project context./review run code review workflow./diff inspect current changes./plan explore and design with read-only tools only./doctor run local diagnostics for config, auth, hooks, and tools./ship run release-oriented workflow./permissions inspect/update tool trust./compact compact session context.Natural language requests are supported too; commands are optional.
Coco currently supports these provider IDs:
anthropicopenaicopilotgeminikimikimi-codegroqopenroutermistraldeepseektogetherhuggingfaceqwenollama (local)lmstudio (local)Notes:
openai supports API-key mode and OAuth flow (mapped internally when needed).copilot and subscription-backed providers rely on their own auth flow.For setup details and model matrix:
Skills are instruction files (SKILL.md) that Coco injects into its context to follow project-specific conventions or workflows. They activate automatically by context or manually via /skill-name.
Where to place skills:
| Location | Scope |
|---|---|
.agents/skills/<skill-name>/SKILL.md | Project — native, highest priority |
~/.coco/skills/<skill-name>/SKILL.md | Global — personal, all projects |
By default, Coco also scans compatible global directories from other agents:
~/.agents/skills/, ~/.claude/skills/, ~/.gemini/skills/, ~/.codex/skills/, and ~/.opencode/skills/.
Coco also reads skills from other agents automatically, so you can bring skills you already have:
| Directory | Agent |
|---|---|
.agents/skills/ | Native (Coco, shared standard) |
.claude/skills/ | Claude Code |
.codex/skills/ | Codex CLI |
.gemini/skills/ | Gemini CLI |
.opencode/skills/ | OpenCode |
Create your first skill:
coco skills create my-conventions
# → creates .agents/skills/my-conventions/SKILL.md
List all skills (including imported from other agents):
coco skills list
See Skills Guide for full documentation.
MCP (Model Context Protocol) lets Coco use external tools: GitHub, databases, APIs, web search, and more.
Quick setup — create .mcp.json in your project root:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token" }
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/path"]
}
}
}
This format is compatible with Claude Code, Cursor, and Windsurf — if you already have a .mcp.json, Coco reads it automatically.
Check MCP status inside the REPL:
/mcp list — show configured servers
/mcp status — show connected servers and available tools
/mcp health — run health check on all servers
Authenticate with environment variables (recommended — never hardcode tokens):
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
},
"my-api": {
"url": "https://api.example.com/mcp",
"headers": { "Authorization": "Bearer ${MY_API_TOKEN}" }
}
}
}
Set the variables in your shell environment (or in ~/.coco/.env for Coco-managed global secrets).
See MCP Guide for full documentation, authentication options, and troubleshooting.
Project-level config in .coco.config.json and CLI-level config via coco config.
Example:
{
"name": "my-service",
"language": "typescript",
"quality": {
"minScore": 88,
"maxIterations": 8
}
}
See:
git clone https://github.com/corbat-tech/coco
cd coco
pnpm install
pnpm build
pnpm test
pnpm check
pnpm check:release
Tech stack:
Release gate (pnpm check:release) runs the stable typecheck/lint/provider+agent suites used for release readiness.
vscode-extension/.Coco sends prompts and selected context to the configured provider.
ollama, lmstudio) keep inference on your machine.Coco is developed by Corbat as an open-source foundation for coding automation and custom AI agents.
MIT © Corbat
FAQs
Autonomous Coding Agent with Self-Review, Quality Convergence, and Production-Ready Output
The npm package @corbat-tech/coco receives a total of 133 weekly downloads. As such, @corbat-tech/coco popularity was classified as not popular.
We found that @corbat-tech/coco demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A new federal program will let vetted U.S. cybersecurity firms help investigate and disrupt foreign cybercrime groups under government direction.
Research
/Security News
The campaign amassed more than 75,000 installs by targeting Russian-speaking users seeking access to blocked services.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.