Tools

Calliope CLI includes built-in tools for executing shell commands, reading and writing files, code execution, web search, git operations, and more.

Available Tools

Shell Tool

Execute any shell command and receive the output.

Parameters

Examples

Running a program:

User: Run the tests
Calliope: Let me run the tests.
[shell] $ npm test

Git operations:

User: Show me the recent commits
Calliope: I'll check the git history.
[shell] $ git log --oneline -10

Checking system state:

User: What's using port 3000?
Calliope: Let me check.
[shell] $ lsof -i :3000

Execution Details

• Working directory: Commands run in your current directory
• Shell: Uses bash (or sh if bash unavailable)
• Timeout: 60 seconds by default
• Environment: Inherits your shell environment

Output Handling

• Standard output and errors are combined
• Exit codes are reported for non-zero exits
• Large outputs are truncated for display

Read File Tool

Read the contents of any file.

Parameters

Examples

Reading source code:

User: Show me the main entry point
Calliope: Let me read the main file.
[read_file] src/index.ts

Checking configuration:

User: What's in the package.json?
Calliope: I'll check the package configuration.
[read_file] package.json

Limitations

• Maximum file size: 1 MB
• Binary files: Not supported (use shell with file command to check type)
• Path security: Restricted to current directory and home folder

Write File Tool

Create new files or overwrite existing ones.

Parameters

Examples

Creating a new file:

User: Create a config file
Calliope: I'll create a configuration file.
[write_file] config.json
{"port": 3000, "debug": true}

Updating code:

User: Add error handling to the API
Calliope: I'll update the API code with error handling.
[write_file] src/api.ts
// Updated content with error handling

Behavior

• Create: Makes new files if they don’t exist
• Overwrite: Replaces existing file contents entirely
• Directories: Creates parent directories if needed
• Path security: Restricted to current directory and home folder

List Files Tool

List the contents of a directory.

Parameters

Examples

List current directory:

User: What files are here?
Calliope: Let me list the files.
[list_files]
📁 src/
📁 tests/
📄 package.json
📄 README.md

List with recursion:

User: Show me the full project structure
Calliope: I'll list all files recursively.
[list_files] recursive=true
📁 src/
  📄 index.ts
  📁 components/
    📄 Button.tsx
    📄 Form.tsx
...

Limitations

• Max depth: 5 levels for recursive listing
• Max entries: 100 files per directory
• Hidden files: Excluded from recursive listings

Think Tool

Structured chain-of-thought reasoning for complex problems.

Parameters

Purpose

The think tool allows Calliope to:

1. Break down complex problems into steps
2. Reason through trade-offs before making decisions
3. Plan multi-step operations before executing
4. Document reasoning in the conversation

Examples

Planning a refactor:

User: Refactor this monolith into microservices
Calliope: This is a complex task. Let me think through it.
[think] I need to:
1. Identify bounded contexts in the existing code
2. Map dependencies between modules
3. Design service boundaries
4. Plan the data migration strategy
5. Create an incremental migration plan

Debugging:

User: The app crashes on startup
Calliope: Let me analyze the possible causes.
[think] Potential causes:
- Missing environment variables
- Database connection failure
- Port already in use
- Missing dependencies
I'll check each of these systematically.

When It’s Used

Calliope automatically uses the think tool when:

• Facing complex, multi-step tasks
• Needing to compare multiple approaches
• Planning before executing destructive operations
• Debugging non-obvious issues

Path Security

All file operations are restricted to safe directories:

Allowed Paths

1. Current working directory and subdirectories
2. Home directory (~) and subdirectories

Blocked Paths

• System directories (/etc, /usr, /var, etc.)
• Other users’ directories
• Path traversal attempts (../../../etc/passwd)

Example

User: Read /etc/passwd
Calliope: Error: Access denied - /etc/passwd is outside allowed directories

Tool Permissions

Normal Mode

In normal mode, you’ll see tool calls before they execute:

[shell] $ rm -rf node_modules
Execute? (y/n)

God Mode

In god mode (-g flag), tools execute without confirmation:

calliope -g

Timeouts

Long-running shell commands will timeout:

[shell] $ npm install
Error: Command timed out after 60 seconds

For longer operations, the AI may need to run commands differently or in chunks.

Execute Code Tool

Run code in a sandboxed environment using Docker (when available).

Parameters

Supported Languages

• Python - Full Python 3 environment
• Node.js - JavaScript/TypeScript runtime
• Bash - Shell scripts

Examples

Running Python:

User: Calculate the first 10 Fibonacci numbers
Calliope: I'll execute that in Python.
[execute_code] python
def fib(n):
    a, b = 0, 1
    result = []
    for _ in range(n):
        result.append(a)
        a, b = b, a + b
    return result
print(fib(10))

Running Node.js:

User: Parse this JSON and extract names
Calliope: I'll process that with Node.js.
[execute_code] node
const data = [{"name": "Alice"}, {"name": "Bob"}];
console.log(data.map(d => d.name).join(", "));

Sandbox Details

When Docker is available:

• Code runs in isolated containers
• Resource limits enforced (memory, CPU)
• Timeout protection
• Network isolation (configurable)
• Working directory mounted read-only

When Docker is unavailable:

• Falls back to local execution
• Shows [unsandboxed] warning
• Still applies timeout limits

Web Search Tool

Search the web for information and documentation.

Parameters

Examples

Finding documentation:

User: How do I use React hooks?
Calliope: Let me search for that.
[web_search] "React hooks tutorial"

Debugging errors:

User: I'm getting ECONNREFUSED on port 3000
Calliope: Let me look that up.
[web_search] "ECONNREFUSED port 3000 Node.js"

Notes

• Results include titles, URLs, and snippets
• Useful for finding current documentation
• Can help debug unfamiliar error messages

Git Tool

Perform common Git operations safely.

Parameters

Supported Operations

Examples

Check status:

User: What's the git status?
Calliope: Let me check.
[git] status

View recent commits:

User: Show me the last 5 commits
Calliope: I'll check the history.
[git] log --oneline -5

Stage and commit:

User: Commit these changes
Calliope: I'll stage and commit the files.
[git] add .
[git] commit -m "Add new feature"

Safety

• Dangerous operations (force push, hard reset) require confirmation
• Read-only operations (status, diff, log) execute immediately
• Working directory must be a git repository

Mermaid Tool

Generate diagrams using Mermaid syntax.

Parameters

Supported Diagram Types

Examples

Flowchart:

User: Create a flowchart for user login
Calliope: I'll generate that diagram.
[mermaid] flowchart
flowchart TD
    A[Start] --> B{Has account?}
    B -->|Yes| C[Enter credentials]
    B -->|No| D[Sign up]
    C --> E{Valid?}
    E -->|Yes| F[Dashboard]
    E -->|No| C

Sequence diagram:

User: Show the API request flow
Calliope: Here's a sequence diagram.
[mermaid] sequence
sequenceDiagram
    Client->>API: POST /login
    API->>DB: Query user
    DB-->>API: User data
    API-->>Client: JWT token

Output

Diagrams are rendered as:

• ASCII preview in terminal
• SVG/PNG file saved to disk (optional)
• Mermaid code for embedding in documentation

Parallel Tool Execution

Calliope automatically parallelizes independent tool calls for better performance.

How It Works

1. Dependency Analysis - Calliope analyzes which tools depend on each other
2. Grouping - Independent operations are grouped together
3. Parallel Execution - Groups execute simultaneously
4. Sequential Fallback - Dependent operations wait for prerequisites

Example

When asked to “check the project status”, Calliope might run in parallel:

• git status
• npm test
• read_file package.json

This provides 2-5x speedup compared to sequential execution.

Visualization

During parallel execution, you’ll see:

[Executing 3 tools in parallel]
├── [git] status
├── [shell] npm test
└── [read_file] package.json

Risk Assessment

All tool operations are classified by risk level:

Higher-risk operations trigger confirmation prompts (unless god-mode is enabled).