English | 中文
Covalo is a terminal-native AI loop agent for making cheap, free, and local models complete real engineering work through supervised execution loops.
Most coding agents assume a strong frontier model is always available. Covalo takes a different position: use stronger models for planning, supervision, and recovery; use cheaper or local models for the bulk of the execution; keep the loop observable, resumable, and governed by explicit safety boundaries.
The goal is not to replace good models. The goal is to make low-cost models useful enough to keep working.
Covalo is a TypeScript/Bun CLI and TUI agent runtime with:
- a cache-aware agent loop optimized for low-cost model usage
- a Supervisor / Worker workflow for long-running engineering tasks
- adjustable harness levels for weak, local, or unreliable models
- a terminal UI built with Ink and React
- 30+ built-in tools for file operations, search, editing, shell, web, tasks, workflow, MCP, and notebooks
- Skills, MCP, and plugin/content-pack integration
- deny-first permission handling for shell commands and file modifications
- session persistence and recovery for interrupted work
Covalo is currently pre-1.0. Core CLI, tools, security, plugin, skills, MCP, and workflow foundations are implemented, but public APIs and configuration formats may still change.
Covalo avoids the fragile pattern of one agent wandering through an unbounded loop. The intended workflow is a fixed two-role execution structure:
Supervisor plans
-> Worker executes
-> Worker reports
-> Supervisor reviews evidence
-> continue, correct, escalate, or ask the human
The Worker is the execution agent. It can use a local model, a free model, or a low-cost API model. In normal chat it behaves like a regular coding agent. In workflow mode, it follows Supervisor instructions and reports progress through structured checkpoints.
The Supervisor uses a stronger model. It is responsible for planning, reviewing Worker reports, reading immutable evidence bundles, detecting failure loops, and producing the next structured instruction. When the workflow cannot safely continue, the Supervisor stops and asks the user.
npm install -g covaloYou can also use Bun:
bun install -g covalocd your-project
covaloInside Covalo, run:
/help
/model
/workflow
/help is the main usage entry point. Ask it for command details, model setup, workflow usage, harness levels, or troubleshooting.
git clone https://github.com/bzcsk2/covalo.git
cd covalo
bun install
bun run dev| Command | Purpose |
|---|---|
/model |
Switch chat target without losing state; configure providers, API keys, and local models. |
/workflow |
Start the Supervisor / Worker workflow. |
/sessions |
List and restore previous sessions after exit or crash. |
/skill |
Browse and activate built-in engineering skills. |
/status |
Inspect runtime, model, provider, tool, and session state. |
/context |
Adjust context strategy. |
/thinking |
Adjust reasoning intensity. |
/harness |
Adjust execution constraints for weak or local models. |
/help |
Show command help and usage guidance. |
Most AI coding tools rely on expensive models to compensate for weak orchestration. Covalo focuses on orchestration first:
- put expensive intelligence where it matters: planning, review, recovery, verification
- let cheap/free/local models do repeatable implementation work
- keep the loop recoverable when the Worker fails
- reduce wasted tokens with cache-aware context management and tool-call repair
Covalo treats model weakness as a runtime condition, not a fatal limitation. The harness system lets the user choose stricter execution rails for weaker models:
- smaller steps
- stronger verification gates
- more frequent reports
- bounded retries
- Supervisor escalation on repeated failure
Covalo is built for developers working in repositories, not for generic chatbot sessions. It emphasizes:
- file-aware edits
- shell execution with permission checks
- resumable sessions
- TUI observability
- project-local configuration
- fast model/provider switching
Covalo uses a kernel/shell separation:
packages/core -> agent loop, API adaptation, context, cache, retry, workflow primitives
packages/tui -> Ink/React terminal UI, input, status, model picker, workflow display
packages/tools -> file, shell, search, edit, web, MCP, workflow, task, notebook tools
packages/plugin -> plugin/content-pack runtime, hooks, schema validation
packages/security -> deny-first PermissionEngine, HookManager, FileSnapshot
packages/cli -> command-line entry point
The engine emits events through an async stream, so the CLI, TUI, tests, and future IDE/web shells can consume the same runtime without coupling UI rendering to agent execution.
CLI / TUI / future IDE shell
│
▼
AsyncGenerator<LoopEvent>
│
▼
CoreEngine
│
┌─────────┼─────────┐
│ │ │
Model Context Tools
Client Manager Executor
Covalo includes tools for:
- reading, writing, editing, and listing files
- grep and project search
- shell execution with policy checks
- TODO/task tracking
- web access
- MCP tool discovery and invocation
- workflow control
- notebook-style operations
Covalo uses layered edit safeguards:
- hash-anchored editing
- fuzzy fallback matching
- stale-read protection
- file snapshots for rollback
- dangerous command blocking
- SSRF-aware web request handling
Skills are reusable domain instruction packages. MCP support lets Covalo connect to external tools and data sources through JSON-RPC 2.0 / stdio MCP servers.
Covalo is designed around multiple model classes:
| Class | Intended role |
|---|---|
| Free gateway models | Low-cost Worker execution, exploration, simple implementation. |
| Local OpenAI-compatible models | Private or continuous Worker execution. |
| API models with user keys | Supervisor, recovery, review, or higher-quality execution. |
| Custom OpenAI-compatible endpoints | vLLM, Ollama, llama.cpp, local gateways, or internal routers. |
Provider configuration is available through /model. Local models are routed through OpenAI-compatible configuration.
Covalo does not require one fixed provider. The runtime state is effectively:
{
provider: string;
baseUrl: string;
model: string;
apiKey?: string;
}Covalo is an agent that can read files, edit files, run commands, and call tools. Treat it as a powerful local development assistant, not as a sandboxed security boundary.
Key safeguards:
- deny-first permission engine
- explicit authorization for shell and write operations
- dangerous command blocking
- file snapshots for rollback
- stale-read checks before edits
- isolated sub-agent permissions
- API key files ignored by Git
Do not run Covalo in a repository where you are not willing to review agent-generated changes.
bun install
bun run typecheck
bun test
bun run build
npm pack --dry-runBefore publishing, run npm pack --dry-run and confirm the package name is covalo and the covalo binary is included.
The package is published as covalo and exposes the covalo binary. The looprig binary is kept as a compatibility alias.
Current primary docs:
Additional design and implementation notes live under docs/. Some files in docs/ are development notes rather than polished user documentation.
See ROADMAP.md.
Near-term focus:
- harden npm installation and package smoke tests
- stabilize Supervisor / Worker workflow behavior
- document provider configuration and harness levels
- improve Windows terminal compatibility
- add reliability benchmarks for weak/local models
Issues and pull requests are welcome. Start with CONTRIBUTING.md, then check open issues and roadmap items.
Covalo is especially interested in contributions around:
- local model presets
- weak-model workflow reliability
- terminal UI polish
- provider adapters
- MCP examples
- documentation and examples
- safety hardening
MIT License. See LICENSE.