Autonomous Loops

Calliope CLI

Autonomous Loops

Run complex, multi-step tasks until completion with autonomous “Ralph Wiggum” loops.

Overview

Autonomous loops allow Calliope to work on a task iteratively until it’s complete. Each iteration:

Receives the prompt you provided
Sees the full conversation history (previous iterations)
Can read files and check state
Makes incremental progress
Repeats until the completion criteria is met

This is ideal for tasks that require multiple steps, feedback loops, or validation.

Basic Usage

Starting a Loop

calliope> /loop "<your prompt>" [options]

Example:

calliope> /loop "Build a REST API with CRUD endpoints for users. Output DONE when complete."

Loop Options

Option	Description	Default
`--max-iterations N`	Maximum iterations before stopping	50
`--completion-promise "text"`	Stop when output contains this text	(none)

Full Example

calliope> /loop "Refactor all TypeScript files to use strict mode. Run tsc after each change. Output DONE when tsc passes with no errors." --max-iterations 30 --completion-promise "DONE"

This will:

Iterate up to 30 times
Stop early if the AI outputs “DONE”
Show progress for each iteration

How Loops Work

Iteration Flow

┌─────────────────────────────────────────┐
│  1. User starts /loop                   │
├─────────────────────────────────────────┤
│  2. Send prompt to AI                   │
│     - Full conversation history         │
│     - Access to tools                   │
├─────────────────────────────────────────┤
│  3. AI responds                         │
│     - May use tools (shell, files)      │
│     - Returns text response             │
├─────────────────────────────────────────┤
│  4. Check completion                    │
│     - Contains completion promise? STOP │
│     - Max iterations reached? STOP      │
│     - Otherwise: continue to step 2     │
└─────────────────────────────────────────┘

Context Accumulation

Each iteration adds to the conversation history:

Iteration 1:
  User: "Build a REST API..."
  Assistant: "Let me create the project structure..."
  [Tool calls and results]

Iteration 2:
  User: "Build a REST API..."  (same prompt)
  [Previous context visible]
  Assistant: "Now I'll add the routes..."
  [Tool calls and results]

Iteration 3:
  User: "Build a REST API..."  (same prompt)
  [All previous context visible]
  Assistant: "Let me run the tests... DONE - all tests pass!"

Stopping Loops

Completion Promise

The cleanest way to stop is with a completion promise:

calliope> /loop "Fix all linting errors. Output DONE when eslint passes." --completion-promise "DONE"

When the AI outputs “DONE” anywhere in its response, the loop stops.

Max Iterations

Always set a reasonable max to prevent runaway loops:

calliope> /loop "..." --max-iterations 20

Default is 50 iterations.

Manual Cancellation

Stop a running loop:

/cancel-loop

Or press ESC on your keyboard.

Best Practices

1. Be Specific About Completion

Bad:

/loop "Build an API"

Good:

/loop "Build a REST API with GET, POST, PUT, DELETE for /users. Run npm test after each change. Output DONE when all tests pass."

2. Include Verification Steps

Include commands to verify progress:

/loop "Migrate the database schema. After each migration, run 'npm run db:status' to verify. Output DONE when all migrations are applied successfully." --max-iterations 15

3. Set Appropriate Limits

Simple tasks: 5-10 iterations
Medium complexity: 15-25 iterations
Complex refactoring: 30-50 iterations

/loop "..." --max-iterations 20

4. Use Clear Success Criteria

The AI needs to know when it’s done:

/loop "Fix type errors in src/. After each fix, run 'tsc --noEmit'. Output DONE when tsc exits with code 0 and reports 0 errors." --completion-promise "DONE"

Use Cases

Code Refactoring

/loop "Convert all class components in src/components/ to functional components with hooks. After each conversion, run 'npm test'. Output DONE when all components are converted and tests pass." --max-iterations 30 --completion-promise "DONE"

Bug Fixing

/loop "The tests in tests/api.test.js are failing. Debug and fix the issues. Run 'npm test' after each change. Output DONE when all tests pass." --max-iterations 15 --completion-promise "DONE"

Project Setup

/loop "Set up a new Express.js project with TypeScript, ESLint, Prettier, and Jest. Create a basic health check endpoint. Run all tools to verify setup. Output DONE when the project is ready." --max-iterations 20 --completion-promise "DONE"

Documentation Generation

/loop "Generate JSDoc comments for all exported functions in src/. After each file, run 'npm run lint' to verify syntax. Output DONE when all files are documented." --max-iterations 25 --completion-promise "DONE"

Dependency Updates

/loop "Update all npm dependencies to their latest versions. After each update, run 'npm test'. If tests fail, investigate and fix. Output DONE when all deps are updated and tests pass." --max-iterations 40 --completion-promise "DONE"

Troubleshooting

Loop Runs Forever

Ensure you set --max-iterations
Make the completion criteria clearer
Use /cancel-loop or ESC to stop

AI Doesn’t Complete the Task

Make instructions more specific
Include verification commands
Increase --max-iterations

AI Gets Stuck in a Loop

If the AI keeps repeating the same action:

Cancel with /cancel-loop
Clear history with /clear
Rephrase the task with more specific instructions

Running Out of Context

For very long loops, context may get truncated. Consider:

Breaking the task into smaller loops
Starting fresh with /clear between major phases
Using a model with larger context (e.g., Claude with 200K context)

Advanced Patterns

Multi-Phase Workflows

Run sequential loops for complex projects:

# Phase 1: Setup
calliope> /loop "Create project structure..." --max-iterations 10 --completion-promise "PHASE1_DONE"

# Phase 2: Implementation
calliope> /loop "Implement the API routes..." --max-iterations 20 --completion-promise "PHASE2_DONE"

# Phase 3: Testing
calliope> /loop "Write and run tests..." --max-iterations 15 --completion-promise "PHASE3_DONE"

Validation-Driven Development

Include continuous validation in your prompt:

/loop "Implement feature X. After each change: 1) Run 'npm test', 2) Run 'npm run lint', 3) Run 'npm run build'. Only proceed if all pass. Output DONE when feature is complete and all checks pass." --max-iterations 30 --completion-promise "DONE"

Providers Tools