Covalo — Terminal-native AI Loop Agent

Core Highlights

Built for cost-aware engineering

Put strong models where they matter, let cheap models do the bulk of the work, and keep the loop observable, resumable, and governed.

💰

Lower Cost

Cache-aware context management, tool-call repair, and multi-provider routing maximize prefix-cache hits and reduce wasted tokens.

🧠

Weak-model Friendly

Adjustable harness levels, small-step execution, failure recovery, and verification gates make unreliable models productive.

⚔️

Supervisor + Worker

A two-role execution structure: Supervisor plans and reviews; Worker executes and reports. Escalate on repeated failure.

✏️

Precise Editing

Hash-anchored edits, fuzzy fallback matching, stale-read protection, and file snapshots for safe rollback.

🧩

30+ Built-in Tools

Files, shell, grep, edit, web, MCP, workflow, task, notebook, cron — plus Skills, plugins, and AgentMemory integration.

🛡️

Safety First

Deny-first permission engine, dangerous command blocking, SSRF-aware web requests, and isolated sub-agent permissions.

Architecture

Kernel / Shell separation

The engine emits events through an async stream, so CLI, TUI, tests, and future IDE/web shells consume the same runtime without coupling.

CLI / TUI / future IDE shell
             │
             ▼
     AsyncGenerator<LoopEvent>
             │
             ▼
        CoreEngine
             │
   ┌─────────┼─────────┐
   │         │         │
 Model   Context  Tools
 Client   Manager   Executor

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/memory

AgentMemory integration and memory tools

packages/security

Deny-first PermissionEngine, HookManager, FileSnapshot

Quick Start

Install and run in minutes

Covalo runs on Bun 1.3+ and works on Linux, macOS, and Windows.

Global install

# npm
$ npm install -g covalo

# or bun
$ bun install -g covalo
    

Start in a project

$ cd your-project
$ covalo
# inside Covalo, run:
#   /help      — main usage entry
#   /model     — switch models / configure providers
#   /workflow  — start Supervisor / Worker workflow
    

Develop from source

$ git clone https://github.com/bzcsk2/covalo.git
$ cd covalo
$ bun install
$ bun run dev
    

Workflow

Supervisor + Worker loop

A fixed two-role execution structure that avoids the fragile pattern of one agent wandering through an unbounded loop.

Supervisor plans

→

Worker executes

→

Worker reports

→

Supervisor reviews

→

Continue / Correct / Escalate

Commands

Common commands

Type /help inside Covalo for full guidance. Here are the most-used commands.

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.