Calliope CLI
The private-AI agent CLI. One terminal agent for any model backend — including the ones you run yourself. MIT-licensed, small core, no lock-in.
npm install -g @calliopelabs/cli
calliope
Single-binary installs are available through Homebrew and a curl installer,
with no Node.js required — see
Install as a single binary.
Why Calliope
- Any backend, live-discovered. Hosted providers, local runtimes, and OpenAI-compatible servers share the same workflow. Models and capabilities are discovered from provider APIs; unsupported or unknown behavior stays explicit. See the provider matrix and real-wire evidence.
- Built for models you run yourself. Ollama and self-hosted OpenAI-compatible servers are first-class targets, not checkboxes. Run fully air-gapped.
- Sandbox-first execution. Shell and code tools run inside macOS Seatbelt or Docker sandboxes (
auto/native/docker/off). Blocklists are advisory; the sandbox is the boundary. - Safety rails that survive long sessions. Circuit breakers, iteration budgets, git-based checkpoints with
/restore, and automatic context compaction. - Governance built in. Tamper-evident audit run logs (on by default), a
replaycommand to inspect and verify them, budget caps that halt a run before it overspends, and a pre-tool policy hook for an external allow/deny engine. See docs/governance.md. - Typed judgments.
calliope judgeevaluates a state against noul/choice/score questions and returns probabilities and confidence your code can branch on, from any backend (including local Ollama) or the native TypeSafe engine. See docs/judgments.md. - Focused command surface. 23 commands, plus optional fleet mode. The command reference documents the available workflows and subcommands.
- Tested like infrastructure. 3,500 tests, 93%+ line coverage with an enforced 90% floor.
What's new in 3.2
3.2 turns the provider foundation into a project workbench: live provider health and
model discovery, /doctor diagnostics, health-aware routing, resumable sessions,
stream-safe retries, and the auto permission mode are available from the same
terminal and headless interfaces. It also adds reviewed orchestration with planner,
worker and verifier roles, isolated execution, bounded retry/replan supervision,
auditable artifacts, and a local Brain/KG for provenance-aware project memory.
The release includes native Bedrock reasoning preservation, Google's @google/genai
adapter, expanded DeepSeek/Cerebras and OpenAI-compatible coverage, and real-wire
provider evidence. See the 3.2.0 release notes for the
complete feature and validation details.
Quick start
calliope --setup # pick a provider, paste a key (or point at Ollama)
calliope # start a session in the current directory
Inside a session:
/mode plan think first — the agent proposes, you approve
/mode auto execute without per-tool approval prompts this session
/model list see live-discovered models for your provider
/defaults save save the current provider/model for this project
/scope add ../lib widen file access deliberately
/compact compress context when it grows
/restore list git checkpoints; /restore <path> to roll back
/help everything else — it fits on one screen
Headless, for CI and scripts:
calliope --headless --json "run the tests and summarize failures"
Plan a project goal within a fixed budget, then approve the returned proposal hash:
calliope orchestrate "Inspect the parser and propose a focused fix" --cost 1 --json
calliope orchestrate approve GOAL_ID PROPOSAL_HASH --allow-mutations --json
Planning exits 5 for review; the goal workflow documents
scope limits, approval, recovery and the JSON contract. /orchestrate presents
the proposed plan and approval dialog in the REPL.
Add --supervise --isolation-image sha256:ID
to propose an isolated work → verify → review → retry/replan loop. Choose separate
controller, worker and optional execution-reviewer models; the existing HUD shows
roles, task attempts and bounded supervision rounds. Planning remains read-only
and execution requires approval of the exact plan.
Execute a reviewed project task graph with bounded agents:
calliope run plan.json --dry-run --json
calliope run plan.json --allow-mutations --json
Independent tasks run concurrently with per-agent permissions and shared budgets. Recorded artifact checks determine completion; unverified criteria require human acceptance. See coordinator execution for plan contracts, provider requirements, cancellation and recovery.
Record and query project knowledge locally, without model requests:
calliope brain init --allow-mutations
calliope brain ingest docs/design.md --allow-mutations
calliope brain search "storage decision" --json
calliope kg graph
The project brain preserves source provenance, supports
human review and reversal, tracks stale documents, and links verified run evidence.
Use /brain and /kg for the same controls in the REPL.
Configuration
One file, 16 keys. Credentials live in a per-provider map with environment-variable fallbacks:
{
"defaultProvider": "anthropic",
"providers": {
"anthropic": { "apiKey": "sk-ant-..." },
"ollama": { "baseUrl": "http://localhost:11434" }
},
"sandboxMode": "auto",
"routing": { "enabled": false, "costSensitivity": 0.3 }
}
ANTHROPIC_API_KEY, OPENAI_API_KEY, OLLAMA_BASE_URL, and friends work as before. v2 configs migrate automatically on first run.
Docs: getting started · commands · configuration · model preferences · providers · features · fleet mode
ChatGPT plan access
Run calliope auth chatgpt login to select subscription-backed OpenAI access.
Use calliope auth chatgpt status to inspect accounts, and api-key to return to
Platform API billing. See ChatGPT plan access for account
management, output/budget restrictions and live-validation requirements.
Editors
Run Calliope as an Agent Client Protocol agent (calliope acp) inside Zed, JetBrains, Neovim, and other ACP editors — client-side file edits, per-tool permissions, and the same audit trail. See docs/acp.md.
Local Claude plan access
Run calliope claude status, then calliope claude -- <prompt> to delegate to your
installed, signed-in Claude agent. Claude owns permissions and plan usage in this
mode. See local Claude delegation.
Fleet mode
Coordinate a fleet of agents and human operators over a self-hosted IRC channel that doubles as an audit trail. Off by default, zero cost when disabled. See docs/fleet.md.
Project memory
Use AGENTS.md for portable repository instructions and CALLIOPE.md for project memory. Trusted instructions load from the checkout root to your working directory, with source paths and directory precedence. /memory sources shows applicable files; /memory reload refreshes them. See repository instructions.
v3.0
v3 is a deliberate reduction: 84 commands, 40 config keys, and ~20k lines of speculative features (theme packs, companions, multi-agent orchestration, an embedded API server, and more) were removed to make the core fast, predictable, and maintainable. The full list and rationale live in CHANGELOG.md and the v3.0 roadmap.
Single-binary installs, enforced performance budgets, governance, ACP editor integration, and local-model edit repair shipped in v3.0. See docs/governance.md and docs/local-models.md.
The next-version roadmap prioritizes consistent execution across providers, portable sessions and instructions, and measured task reliability. The first implementation adds cancellation through provider requests, retries and local processes, plus scoped AGENTS.md support. See cancellation behavior.
Contributing
Issues and PRs welcome — CONTRIBUTING.md. The codebase is TypeScript ESM with React/Ink; npm test must stay green and coverage must stay above 90%.
License
MIT © Calliope Labs Inc
Code migration kit
The packaged migration playbook provides versioned
inventory, baseline, assessment and verification helpers for the initial
JavaScript-to-TypeScript CLI adapter. Discover them offline with
calliope migration capabilities --json; native reviewed execution remains the
authority for worker commands, budgets and file scope.