Calliope CLI

Multi-model AI agent for your terminal. Switch between Claude, GPT, Gemini, and 10+ other providers with intelligent auto-routing and persistent project memory.

Overview

Calliope CLI is an open-source terminal AI agent that brings the power of multiple AI providers to your command line. Install globally, run anywhere, and switch models on the fly without changing your workflow.

npm install -g @calliopelabs/cli
calliope

Key capabilities:

100% BYOK - Bring your own API keys. Direct to providers, no middleman
12+ AI providers - Anthropic, OpenAI, Google, Mistral, Groq, Together, and more
Auto model routing - Intelligently select models based on task complexity
Project memory - Persistent context across sessions via CALLIOPE.md
Autonomous loops - Run complex tasks until completion
Sandboxed execution - Safe code execution via Docker
Tool hooks - Custom pre/post scripts for tool execution
Zero config - Environment variables or interactive setup

Quick Start

Installation

npm install -g @calliopelabs/cli

First Run

calliope

On first run, you’ll be guided through:

Selecting an AI provider (Anthropic, Google, OpenAI, etc.)
Entering your API key
Choosing a persona (Calliope, Professional, or Minimal)

Skip Setup with Environment Variables

export ANTHROPIC_API_KEY=sk-ant-...
calliope

Features

Multi-Model Support

Switch between providers instantly:

/provider anthropic    # Use Claude
/provider google       # Use Gemini
/provider openai       # Use GPT
/provider mistral      # Use Mistral
/provider ollama       # Use local models
/provider openrouter   # Access any model via OpenRouter

Auto Model Routing

Automatically select the optimal model based on task complexity:

/route on              # Enable auto-routing
/route test "explain quantum computing"  # Test routing decision
/route off             # Disable auto-routing

Model tiers:

Fast: Haiku, GPT-4o Mini, Flash - quick, simple tasks
Balanced: Sonnet, GPT-4o, Pro - moderate complexity
Smart: Opus, o1, Pro - complex reasoning tasks

Project Memory (CALLIOPE.md)

Persistent memory across sessions using markdown files:

/memory init           # Create CALLIOPE.md
/memory add context "This is a TypeScript project"
/memory add preference "Use functional components"
/memory show           # View project memory
/memory global         # View global preferences

Calliope automatically loads context from standard files:

CALLIOPE.md - Project memory
CLAUDE.md - Claude context
README.md, SPEC.md, TODO.md
ARCHITECTURE.md, DESIGN.md, NOTES.md
.cursorrules, .github/copilot-instructions.md

Hooks System

Run custom scripts before/after tool execution:

/hooks init            # Initialize default hooks
/hooks list            # Show configured hooks
/hooks add pre-shell "echo Running: $CALLIOPE_COMMAND"

Hook events: pre-tool, post-tool, pre-shell, post-shell, pre-write, post-write, session-start, session-end

Hooks can block operations by returning exit code 42.

Context Summarization

Manage long conversations:

/summarize context     # View conversation summary
/summarize compact     # Compress context to fit limits

Autonomous Loops

Run complex tasks until completion with “Ralph Wiggum” loops:

/loop "Build a REST API with CRUD operations. Output DONE when complete." --max-iterations 20 --completion-promise "DONE"

Each iteration sees the full conversation history and can make incremental progress. The loop stops when:

The AI outputs the completion promise text
Max iterations are reached
You press ESC or run /cancel-loop

Tool Access

Calliope has built-in tools for common operations:

Tool	Description
shell	Execute any shell command
read_file	Read file contents
write_file	Create or overwrite files with diff preview
list_files	List directory contents
think	Structured chain-of-thought reasoning
execute_code	Run Python/Node/Bash in sandbox
web_search	Search the web
git	Git operations
mermaid	Generate diagrams

Sandboxed Code Execution

Execute code safely in Docker containers:

The execute_code tool automatically:
- Uses Docker when available (recommended)
- Falls back to local execution
- Shows [sandboxed] or [unsandboxed] status
- Enforces resource limits and timeouts

MCP Server Support

Connect external tools via Model Context Protocol:

/mcp add https://mcp-server.example.com
/mcp list              # Show connected servers
/mcp tools             # List available tools
/mcp refresh           # Reconnect all servers

Agent Skills

Install reusable skills from the registry:

/skills add git-workflow
/skills add code-review
/skills list
/skills info <name>

Conversation Branching

Fork conversations to explore different approaches:

/branch new experiment "Try approach B"
/branch list
/branch switch experiment
/branch delete experiment

Themes

Customize the color scheme:

/theme list            # Show available themes
/theme monokai         # Set theme

Available themes: default, light, monokai, nord, minimal

Personas

Choose your interaction style:

Persona	Description
calliope	Poetic, creative, expressive
professional	Clear, concise, business-appropriate
minimal	Extremely brief responses

/persona professional

God Mode

Run without permission prompts for trusted tasks:

calliope -g
calliope --god-mode

God mode executes all tool calls without confirmation. Only use for well-defined tasks in trusted directories.

Operating Modes

Calliope has three operating modes that control how it handles tasks:

Mode	Icon	Behavior
Plan	📋	Chat only, no tool execution. Use for design discussions.
Hybrid	🔄	Smart planning before complex operations. Default mode.
Work	🔧	Direct execution without planning. For experienced users.

/mode plan              # Switch to plan mode
/mode hybrid            # Switch to hybrid mode (default)
/mode work              # Switch to work mode
/plan                   # Quick switch to plan mode
/work                   # Quick switch to work mode

Multi-Agent Mode (AGTerm)

Enable multi-agent orchestration for complex tasks:

calliope -a
calliope --agterm

In AGTerm mode, Calliope can spawn sub-agents (Claude, Gemini, etc.) to work on parallel tasks. Features include:

Parallel task execution
Task queueing and prioritization
Nested sub-agent support
Automatic result aggregation

Legacy Mode

Use the simpler readline-based interface:

calliope --legacy

The legacy mode supports core features including:

All AI providers and models
Autonomous loops
Tool execution
Memory loading
Hooks

Cost Tracking

Track token usage and costs across sessions:

/cost                   # Show session cost breakdown
/cost reset             # Reset cost tracking

Cost tracking includes:

Input/output token counts
Cost per provider
Session and cumulative totals

Commands Reference

Core

Command	Description
`/help`, `/h`	Show all commands
`/exit`, `/quit`, `/q`	Exit Calliope
`/clear`, `/c`	Clear conversation
`/status`, `/s`	Show current status
`/config`	Show configuration path
`/debug [on\|off]`	Toggle debug mode
`/upgrade`	Check for updates

Model & Provider

Command	Description
`/provider`, `/p [name]`	Switch AI provider
`/model`, `/m [name]`	Set model (interactive if no name)
`/models`	Browse available models
`/route [on\|off\|test]`	Auto model routing
`/autoroute`	Alias for `/route`
`/persona [name]`	Switch persona

Operating Modes

Command	Description
`/mode [plan\|hybrid\|work]`	Switch operating mode
`/plan`	Quick switch to plan mode (chat only)
`/work`	Quick switch to work mode (direct execution)
`/confirm [on\|off]`	Toggle confirmation for risky operations
`/set <key> <value>`	Set runtime config (e.g., maxIterations)

Memory & Context

Command	Description
`/memory [init\|add\|show\|global]`	Project memory
`/summarize [context\|compact]`	Summarize conversation
`/context`	Show loaded project context

Extensions

Command	Description
`/mcp [list\|add\|remove\|tools\|refresh]`	MCP servers
`/skills [list\|add\|remove\|info]`	Agent skills
`/hooks [list\|add\|init]`	Pre/post tool hooks

Scope & Security

Command	Description
`/scope`	Show current scope restrictions
`/scope add <path>`	Add directory to allowed scope
`/scope remove <path>`	Remove directory from scope
`/scope reset`	Clear all scope restrictions
`/scope details`	Show detailed scope info
`/add-dir <path>`	Add directory (alias)
`/remove-dir <path>`	Remove directory (alias)

Navigation & History

Command	Description
`/find <pattern>`	Fuzzy file search
`/search <query>`	Search conversation history
`/history [search]`	View conversation history
`/branch [new\|switch\|list\|delete]`	Conversation branches
`/bookmark "name"`	Create a bookmark
`/bookmarks`	List all bookmarks
`/goto <id>`	Jump to bookmark
`/undo`	Undo last exchange
`/redo`	Redo exchange

Session & Templates

Command	Description
`/session`	Show current session info
`/session list`	List all sessions
`/template save <name> <prompt>`	Save a template
`/template list`	View all templates
`/template use <name>`	Use a template
`/template delete <name>`	Remove a template

Interface & Cost

Command	Description
`/theme [name\|list]`	Color themes
`/copy`	Copy last response
`/export [file.md]`	Export conversation
`/profile [name\|save\|list\|delete]`	Switch/save configuration profiles
`/cost`	Show cost breakdown for session
`/cost reset`	Reset cost tracking
`/costs`	Alias for `/cost`

Keyboard Shortcuts

Key	Action
`ESC`	Exit
`Shift+Tab`	Cycle modes
`Ctrl+C`	Cancel operation
`Ctrl+L`	Clear screen
`Up/Down`	Navigate history
`Tab`	Tab completion

File References

Reference files directly in your messages:

@filename.ts           # Include file content
./path/to/file         # Relative path
/absolute/path/file    # Absolute path

Images are automatically detected and sent for vision models.

Documentation

Installation

System requirements and setup

Bring Your Own Keys

BYOK philosophy and setup

Providers

Configure AI providers and models

Autonomous Loops

Run tasks to completion

Tools

Shell, files, code execution, and more

Configuration

Settings, profiles, and preferences

Scope & Security

File access, risk levels, and sandboxing

API Key Security

Secure storage and best practices