@calliopelabs/cli 0.6.11 → 0.7.1

package/README.md

@@ -18,6 +18,10 @@ Multi-model AI agent CLI with autonomous loops, project memory, and advanced too
 ## Installation
 
 ```bash
+# Quick install
+curl -fsSL https://calliope.ai/install.sh | bash
+
+# Or via npm
 npm install -g @calliopelabs/cli
 ```
 
@@ -49,24 +53,174 @@ Switch between 12+ providers on the fly:
 /provider mistral      # Use Mistral
 /provider ollama       # Use local models
 /provider openrouter   # Use any model via OpenRouter
-/provider litellm      # Use LiteLLM proxy
 ```
 
-### Auto Model Routing
+**Supported Providers:**
+- Anthropic (Claude): Sonnet 4, Opus 4, Haiku
+- OpenAI: GPT-4o, o1, o3-mini
+- Google: Gemini 2.0 Flash, 1.5 Pro
+- Mistral: Large, Small
+- Groq: Llama 3.3, Mixtral
+- Cerebras: Llama 3.3
+- Fireworks: Llama models
+- xAI: Grok
+- Ollama: Local models
+- OpenRouter: 100+ models
+- GitHub Models: Via Azure
+- DeepSeek: R1, V3
+
+### 🔒 Scope Management
+
+Control which directories your AI can access for enhanced security:
+
+```bash
+/scope add ./src              # Grant access to src directory
+/scope add ./tests            # Add tests directory
+/scope list                   # View current scope
+/scope remove ./src           # Revoke access
+/scope reset                  # Clear all scope restrictions
+```
+
+**Benefits:**
+- 🔒 **Security** - Prevent accidental modifications outside project areas
+- 🎯 **Focus** - Keep AI operations within relevant directories
+- ⚡ **Performance** - Reduce unnecessary file scanning
+- 📋 **Audit trail** - Track which directories are in scope
+
+### 🔁 Session Management & Continuity
+
+Seamless continuity between sessions:
+
+```bash
+# On startup, Calliope detects previous sessions:
+╭─ 🎭 Calliope v0.6.11
+│  Found previous session (2 hours ago)
+│    • 12 messages, 2 TODOs pending
+╰─ [R]esume  [N]ew session
+
+# Commands
+/session list          # List all sessions
+/session info          # Current session details
+/history               # View conversation history
+/export [file.md]      # Export conversation to markdown
+```
+
+### 🔖 Bookmarks & Navigation
+
+Mark and return to important moments in your conversation:
+
+```bash
+/bookmark "Got auth working"    # Create a bookmark
+/bookmarks                      # List all bookmarks
+/goto bookmark-1                # Jump to that point in history
+/bookmark delete 1              # Remove a bookmark
+```
+
+**Use cases:**
+- Mark successful implementations
+- Save decision points
+- Quick navigation in long conversations
+
+### 📋 Templates
+
+Save and reuse common prompts and workflows:
+
+```bash
+/template save code-review "Review this code for bugs, performance, and best practices"
+/template list                  # View all templates
+/template use code-review       # Use a saved template
+/template delete code-review    # Remove a template
+```
+
+**Built-in templates include:**
+- Code review
+- Bug investigation
+- Refactoring plans
+- Testing strategies
+
+### ↩️ Undo/Redo
+
+Navigate conversation history with full state management:
+
+```bash
+/undo                  # Undo last exchange (message + all responses)
+/redo                  # Redo previously undone exchange
+/history               # View full conversation timeline
+```
+
+**Features:**
+- Preserves entire conversation state
+- Works across tool executions
+- Unlimited undo/redo stack
+- Shows available undo/redo count
+
+### 💰 Cost Tracking
+
+Monitor API usage and costs across sessions:
+
+```bash
+# Automatic tracking in status bar:
+# anthropic:claude-sonnet-4 │ 5.2K/200K │ 12.5K used │ $0.45
+
+/cost                  # Detailed cost breakdown
+```
+
+**Tracks:**
+- Current session cost
+- Total cost across all sessions
+- Cost per provider
+- Token usage (input/output)
+- Persists across sessions
+
+### ⌨️ Advanced Input Experience
+
+Enhanced input with modern conveniences:
+
+- **Tab completion** - Slash commands and file paths autocomplete
+- **History navigation** - Up/down arrows to browse previous inputs
+- **Multi-line editing** - Shift+Enter for new lines (if supported)
+- **Path suggestions** - Real-time file path completion
+- **Command hints** - Footer shows available options
+
+**Example:**
+```
+> /boo[TAB]           → /bookmark
+> /scope add ./[TAB]  → ./src/  ./tests/  ./docs/
+> [Up Arrow]          → Previous command
+```
+
+### 🚀 Parallel Tool Execution
 
-Automatically select the best model based on task complexity:
+Automatically executes independent tool calls in parallel for 2-5x speedup:
 
 ```
-/route on              # Enable auto-routing
-/route test "explain quantum computing"  # Test routing decision
+# When AI needs to read 3 files:
+Sequential: Read file1 → wait → Read file2 → wait → Read file3
+Parallel:   Read file1, file2, file3 → all at once!
+
+# Dependency-aware:
+- Detects when tools depend on each other
+- Executes in optimal order
+- Shows parallel execution progress
 ```
 
-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
+### ⚡ Autonomous Loops
+
+Enable continuous execution for complex multi-step tasks:
+
+```bash
+/loop on               # Enable autonomous loops
+/loop off              # Disable
+/loop 10               # Set max iterations
+
+# The AI will:
+# 1. Plan the approach
+# 2. Execute tools
+# 3. Evaluate results
+# 4. Continue until goal achieved or max iterations
+```
 
-### Project Memory (CALLIOPE.md)
+### 🧠 Project Memory (CALLIOPE.md)
 
 Persistent memory across sessions using markdown files:
 
@@ -85,221 +239,281 @@ Calliope automatically loads context from standard files:
 - `ARCHITECTURE.md`, `DESIGN.md`, `NOTES.md`
 - `.cursorrules`, `.github/copilot-instructions.md`
 
-### Tools
+### 🛠️ Tools
 
 Built-in tools for autonomous operation:
 
 | Tool | Description |
 |------|-------------|
-| `shell` | Execute shell commands |
+| `shell` | Execute shell commands with safety checks |
 | `read_file` | Read file contents |
 | `write_file` | Write files with diff preview |
 | `list_files` | Directory listing |
-| `think` | Structured reasoning |
+| `think` | Structured reasoning (visible in output) |
 | `execute_code` | Run Python/Node/Bash in sandbox |
-| `web_search` | Search the web |
-| `git` | Git operations |
+| `web_search` | Search the web for information |
+| `git` | Git operations (status, diff, log, etc.) |
 | `mermaid` | Generate diagrams |
 
-### Sandboxed Code Execution
+### 🐳 Sandboxed Code Execution
 
 Execute code safely in Docker containers:
 
 ```
 The execute_code tool automatically:
 - Uses Docker when available (recommended)
-- Falls back to local execution
+- Falls back to local execution if needed
 - Shows [sandboxed] or [unsandboxed] status
 - Enforces resource limits and timeouts
 ```
 
-### MCP Server Support
+### 🌐 MCP Server Support
 
 Connect external tools via Model Context Protocol:
 
-```
+```bash
 /mcp add https://mcp-server.example.com
 /mcp list              # Show connected servers
-/mcp tools             # List available tools
+/mcp tools             # List available tools from all servers
 /mcp refresh           # Reconnect all servers
 ```
 
-### Agent Skills (AgentSkills.io)
+### 📦 Agent Skills (AgentSkills.io)
 
-Install reusable skills from the registry:
+Install reusable skills from the community registry:
 
-```
+```bash
 /skills add git-workflow
 /skills add code-review
-/skills list
-/skills info <name>
+/skills list           # Show installed skills
+/skills info <name>    # Skill details
 ```
 
-### Conversation Branching
+### 🌲 Conversation Branching
 
 Fork conversations to explore different approaches:
 
-```
+```bash
 /branch new experiment "Try approach B"
-/branch list
+/branch list           # Show all branches
 /branch switch experiment
 /branch delete experiment
 ```
 
-### Themes
+### 🎨 Themes & Personas
 
-Customize the color scheme:
+Customize the visual style and AI personality:
 
-```
+```bash
+# Themes
 /theme list            # Show available themes
 /theme monokai         # Set theme
+/theme                 # Cycle through themes
+
+# Personas
+/persona professional  # Professional, concise responses
+/persona minimal       # Minimal output, just essentials
+/persona calliope      # Poetic, elegant responses (default)
 ```
 
-Available themes: `default`, `light`, `monokai`, `nord`, `minimal`
+**Available themes:** `default`, `light`, `monokai`, `nord`, `minimal`
 
-### Hooks System
+### 🪝 Hooks System
 
 Run custom scripts before/after tool execution:
 
-```
+```bash
 /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`
+**Hook events:** `pre-tool`, `post-tool`, `pre-shell`, `post-shell`, `pre-write`, `post-write`, `session-start`, `session-end`
 
-### Context Summarization
+### 📊 Context Management & Warnings
 
-Manage long conversations:
+Smart context tracking with proactive warnings:
+
+```
+⚠️  Context at 85% capacity (170K/200K tokens)
+   Consider: /summarize compact | /clear | shorter messages
 
+🚨 Context at 95% capacity! (190K/200K tokens)
+   Action required: /summarize compact | /clear
 ```
+
+**Commands:**
+```bash
 /summarize context     # View conversation summary
 /summarize compact     # Compress context to fit limits
+/clear                 # Clear conversation
 ```
 
-### Project Configuration (.calliope)
+### 🔍 Smart Search
 
-Human-readable project config:
+Find anything in your conversation or project:
 
-```
-/project init          # Create .calliope file
-/project show          # View config
-/project run build     # Run defined command
+```bash
+/search error handling    # Fuzzy search through history
+/find auth               # Find files in project
 ```
 
-Format:
+### ⚙️ Modes
+
+Three distinct operating modes for different workflows:
+
+```bash
+/mode plan             # Analyze and plan, don't execute
+/mode hybrid           # Plan then execute (default)
+/mode work             # Execute directly without planning
 ```
-project: My Project
-provider: anthropic
-model: claude-sonnet-4-20250514
 
-[tech]
-typescript
-react
-postgres
+| Mode | Icon | Behavior | Use Case |
+|------|------|----------|----------|
+| **Plan** | 📋 | Chat only, no execution | Design discussions, exploration |
+| **Hybrid** | 🔄 | Smart planning before complex ops | Default for most users |
+| **Work** | 🔧 | Direct execution | Experienced users, simple tasks |
 
-[conventions]
-Use functional components
-Prefer async/await
+### 🛡️ Risk Assessment & Safety
 
-[commands]
-build: npm run build
-test: npm test
-```
+Built-in safety for potentially dangerous operations:
+
+- Automatic risk classification (low/medium/high/critical)
+- Permission prompts for risky operations
+- God mode (`-g`) to bypass prompts for trusted tasks
+- Detailed explanations of risks
+- Scope restrictions for file access
+
+### 🚄 Streaming & Real-time Feedback
+
+Live response rendering for immediate feedback:
+
+- Token-by-token streaming for text responses
+- Live tool execution status with progress indicators
+- Visual diffs for file changes
+- Parallel tool execution visualization
+- Thinking process display
 
 ## Commands Reference
 
-### Core
-| Command | Description |
-|---------|-------------|
-| `/help` | Show all commands |
-| `/exit` | Exit Calliope |
-| `/clear` | Clear conversation |
-| `/status` | Show current status |
-| `/config` | Show configuration |
+### Core Commands
+```bash
+/help, /h              # Show all commands
+/exit, /quit, /q       # Exit Calliope
+/clear, /c             # Clear conversation
+/status, /s            # Show current status
+/config                # Show configuration
+/debug [on|off]        # Toggle debug mode
+```
 
 ### Model & Provider
-| Command | Description |
-|---------|-------------|
-| `/provider [name]` | Switch AI provider |
-| `/model [name]` | Set model (interactive if no name) |
-| `/models` | Browse available models |
-| `/route [on\|off\|test]` | Auto model routing |
-| `/persona [name]` | Switch persona |
-
-### Modes
-| Command | Description |
-|---------|-------------|
-| `/mode [plan\|hybrid\|work]` | Switch operating mode |
-| `/confirm [on\|off]` | Toggle risky op confirmation |
-
-Modes:
-- **Plan**: Analyze and plan, don't execute
-- **Hybrid**: Plan then execute (default)
-- **Work**: Execute without planning
+```bash
+/provider, /p [name]   # Switch AI provider
+/model, /m [name]      # Set model (interactive if no name)
+/models                # Browse available models
+/persona [name]        # Switch persona (calliope/professional/minimal)
+```
+
+### Modes & Settings
+```bash
+/mode [plan|hybrid|work]  # Switch operating mode
+/loop [on|off|N]       # Toggle/configure autonomous mode
+/confirm [on|off]      # Toggle risky operation confirmation
+/theme [name]          # Switch theme
+```
+
+### Scope Management
+```bash
+/scope add <path>      # Add directory to scope
+/scope remove <path>   # Remove directory from scope
+/scope list            # Show current scope
+/scope reset           # Clear all scope restrictions
+```
 
 ### Session & History
-| Command | Description |
-|---------|-------------|
-| `/session [list\|info]` | Session management |
-| `/history [search]` | Chat history |
-| `/context [load\|summary]` | Context management |
-| `/summarize [context\|compact]` | Summarize conversation |
-
-### Memory & Config
-| Command | Description |
-|---------|-------------|
-| `/memory [init\|add\|show\|global]` | Project memory |
-| `/project [init\|show\|run]` | Project config |
-| `/profile [name\|save\|del]` | Switch/save profiles |
-
-### Search & Navigation
-| Command | Description |
-|---------|-------------|
-| `/find <pattern>` | Fuzzy file search |
-| `/search <query>` | Search conversation |
-| `/branch [new\|switch\|list]` | Conversation branches |
+```bash
+/session list          # List all sessions
+/session info          # Current session details
+/history [search]      # View/search conversation history
+/bookmark [name]       # Create bookmark
+/bookmarks             # List bookmarks
+/goto <id>             # Jump to bookmark
+/undo                  # Undo last exchange
+/redo                  # Redo exchange
+```
+
+### Templates & Memory
+```bash
+/template save <name> <prompt>  # Save template
+/template list         # View all templates
+/template use <name>   # Use template
+/template delete <name> # Remove template
+
+/memory init           # Initialize project memory
+/memory add <text>     # Add to memory
+/memory show           # View project memory
+/memory global         # View global memory
+```
+
+### Context & Search
+```bash
+/summarize [context|compact]  # Summarize/compress conversation
+/search <query>        # Search conversation history
+/find <pattern>        # Fuzzy file search in project
+/branch [new|switch|list]  # Conversation branches
+```
 
 ### Tools & Extensions
-| Command | Description |
-|---------|-------------|
-| `/mcp [list\|add\|remove\|tools]` | MCP servers |
-| `/skills [list\|add\|remove\|info]` | Agent skills |
-| `/hooks [list\|add\|init]` | Pre/post tool hooks |
+```bash
+/mcp [list|add|remove|tools]  # MCP server management
+/skills [list|add|remove|info] # Agent skills
+/hooks [list|add|init] # Pre/post tool hooks
+```
 
 ### Tasks & Planning
-| Command | Description |
-|---------|-------------|
-| `/todo [add\|done\|list]` | Manage TODOs |
-| `/plans [list\|view]` | View plan history |
-
-### Interface
-| Command | Description |
-|---------|-------------|
-| `/theme [name\|list]` | Color themes |
-| `/copy` | Copy last response |
-| `/export [file.md]` | Export conversation |
-| `/edit` | Edit last message |
-| `/undo` | Remove last exchange |
-| `/upgrade` | Check for updates |
+```bash
+/todo [add|done|work|clear|list]  # Manage TODOs
+/plans [list|view|rerun]          # View and rerun plans
+```
+
+### Utility
+```bash
+/cost                  # Show cost breakdown
+/copy                  # Copy last response
+/export [file.md]      # Export conversation to file
+/upgrade               # Check for updates
+/set <key> <value>     # Set runtime config (e.g., maxIterations)
+/context               # Show loaded project context
+```
 
 ## Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `ANTHROPIC_API_KEY` | Anthropic Claude API key |
-| `GOOGLE_API_KEY` | Google Gemini API key |
-| `OPENAI_API_KEY` | OpenAI API key |
-| `OPENROUTER_API_KEY` | OpenRouter API key |
-| `TOGETHER_API_KEY` | Together AI API key |
-| `GROQ_API_KEY` | Groq API key |
-| `MISTRAL_API_KEY` | Mistral AI API key |
-| `AI21_API_KEY` | AI21 Labs API key |
-| `HUGGINGFACE_API_KEY` | HuggingFace API key |
-| `OLLAMA_BASE_URL` | Ollama server URL (default: localhost:11434) |
-| `LITELLM_BASE_URL` | LiteLLM proxy URL (default: localhost:4000) |
-| `LITELLM_API_KEY` | LiteLLM API key (if required) |
+```bash
+# API Keys
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+GOOGLE_API_KEY=...
+MISTRAL_API_KEY=...
+GROQ_API_KEY=...
+XAI_API_KEY=...
+CEREBRAS_API_KEY=...
+FIREWORKS_API_KEY=...
+DEEPSEEK_API_KEY=...
+OPENROUTER_API_KEY=...
+
+# Configuration
+CALLIOPE_PROVIDER=anthropic
+CALLIOPE_MODEL=claude-sonnet-4-20250514
+CALLIOPE_GOD_MODE=false
+CALLIOPE_DEBUG=false
+
+# Ollama
+OLLAMA_BASE_URL=http://localhost:11434
+
+# LiteLLM
+LITELLM_BASE_URL=http://localhost:4000
+LITELLM_API_KEY=...
+```
 
 ## Configuration
 
@@ -316,29 +530,47 @@ calliope --reset
 calliope --setup
 ```
 
+### Sample config.json
+```json
+{
+  "provider": "anthropic",
+  "model": "claude-sonnet-4-20250514",
+  "apiKeys": {
+    "anthropic": "sk-ant-...",
+    "openai": "sk-...",
+    "google": "..."
+  },
+  "theme": "default",
+  "persona": "calliope",
+  "godMode": false,
+  "maxIterations": 25,
+  "scope": ["./src", "./tests"]
+}
+```
+
 ### Profiles
 
 Save and switch between configurations:
 
-```
-/profile save work     # Save current settings
-/profile work          # Load profile
+```bash
+/profile save work     # Save current settings as "work"
+/profile work          # Load "work" profile
 /profile delete work   # Delete profile
 /profile list          # Show all profiles
 ```
 
-Built-in profiles: `fast`, `smart`, `cheap`, `local`
+**Built-in profiles:** `fast`, `smart`, `cheap`, `local`
 
 ## Keyboard Shortcuts
 
 | Key | Action |
 |-----|--------|
-| `ESC` | Exit |
-| `Shift+Tab` | Cycle modes |
-| `Ctrl+C` | Cancel operation |
+| `ESC` | Exit Calliope |
+| `Ctrl+C` | Cancel current operation |
 | `Ctrl+L` | Clear screen |
-| `Up/Down` | Navigate history |
-| `Tab` | Tab completion |
+| `Up/Down` | Navigate input history |
+| `Tab` | Autocomplete commands/paths |
+| `Shift+Enter` | Multi-line input (where supported) |
 
 ## File References
 
@@ -350,43 +582,110 @@ Reference files directly in your messages:
 /absolute/path/file    # Absolute path
 ```
 
-Images are automatically detected and sent for vision models.
+Images are automatically detected and sent for vision-capable models.
 
-## Security
+## Security & Best Practices
 
 ### API Key Storage
 - Keys stored in `~/.config/calliope/config.json`
 - Prefer environment variables for better security
 - Never commit config to version control
 
-### Tool Execution
+### Tool Execution Safety
 - Path traversal protection
 - Sandboxed code execution via Docker
 - Timeout limits on all commands
+- Risk assessment for dangerous operations
+- Scope restrictions for file access
 - Hook system for custom validation
 
 ### Best Practices
-1. Review tool calls before execution
-2. Use god mode (`-g`) only for trusted tasks
-3. Set iteration limits on loops
+1. Use `/scope` to limit directory access
+2. Review tool calls before execution (unless in god mode)
+3. Set iteration limits on autonomous loops
 4. Work from project directories, not system directories
+5. Regular `/summarize` to manage context
+6. Use bookmarks for important moments
+
+## Development
+
+```bash
+# Clone and setup
+git clone https://github.com/calliopeai/calliope-cli.git
+cd calliope-cli
+npm install
+
+# Build
+npm run build
+
+# Run locally
+node dist/bin.js
+
+# Run tests
+npm test
+
+# Watch mode for development
+npm run dev
+```
+
+## Architecture
+
+- **TypeScript** - Full type safety throughout
+- **Ink (React)** - Declarative CLI rendering
+- **Vitest** - Fast unit testing framework
+- **Multi-provider** - Unified interface for 12+ LLM providers
+- **Modular design** - Clean separation of concerns
+- **Parallel execution** - Dependency-aware tool execution
+- **Error boundaries** - Graceful crash recovery
 
 ## Troubleshooting
 
 **"No API keys configured"**
-- Run `calliope --setup` or set environment variable
+- Run `calliope --setup` to configure keys
+- Or set environment variables (see above)
 
 **"Empty response from API"**
-- Check API key validity and credits
+- Check API key validity
+- Verify account credits/quota
 - Try a different provider
 
+**Context limit warnings**
+- Use `/summarize compact` to compress
+- Or `/clear` to start fresh
+- Consider shorter messages
+
 **"Access denied" for file operations**
 - Operations restricted to cwd and home directory
+- Check `/scope list` for current restrictions
+- Use `/scope add <path>` to grant access
 
 **Docker not available for sandbox**
 - Install Docker for safer code execution
-- Without Docker, code runs locally (unsandboxed)
+- Without Docker, code runs locally (less safe)
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE)
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/calliopeai/calliope-cli/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/calliopeai/calliope-cli/discussions)
+- **Twitter**: [@calliopelabs](https://twitter.com/calliopelabs)
+
+## Acknowledgments
+
+Built with love by the Calliope team. Special thanks to:
+- Anthropic for Claude
+- OpenAI for GPT
+- Google for Gemini
+- The open-source community
+- All contributors and users
+
+---
+
+*May your code be elegant, your execution swift, and your automation poetic.* 🎭✨