Skills
skills/adaptationio/skrillz/autonomous-opus-loop

autonomous-opus-loop

SKILL.md

Autonomous Opus Loop

Transform Claude Code from interactive to fully autonomous using an external Opus 4.5 instance to analyze progress and decide continuation.

Overview

This skill enables Claude Code to run autonomously by using another Claude instance (Opus 4.5) to:

  • Analyze work progress after each response
  • Decide whether to continue or stop
  • Provide specific next-step instructions
  • Maintain momentum until objectives are achieved

Key Innovation: The Stop hook's reason field becomes Claude's next instruction, creating a fully autonomous loop where two Claude instances collaborate.

Architecture

┌─────────────────────────────────────┐
│  Claude Code (Executor)             │
│  - Executes tasks                   │
│  - Writes code, runs tests          │
│  - Triggers Stop hook when done     │
└─────────────────┬───────────────────┘
                  │
                  ▼ (Stop hook fires)
        ┌─────────────────────────────┐
        │  autonomous-loop.sh         │
        │  - Reads transcript         │
        │  - Checks safety limits     │
        │  - Calls Opus analyzer      │
        └──────────┬──────────────────┘
                   │
                   ▼
   ┌───────────────────────────────────┐
   │  Claude Opus 4.5 (Analyzer)       │
   │  - Reviews all work done          │
   │  - Checks against objectives      │
   │  - Decides: CONTINUE or COMPLETE  │
   │  - If CONTINUE: specific next task│
   └──────────┬────────────────────────┘
              │
              ▼
        ┌─────────────────────────────┐
        │  Loop Controller            │
        │  - Tracks iterations        │
        │  - Monitors cost            │
        │  - Prevents doom loops      │
        │  - Returns decision to CC   │
        └──────────┬──────────────────┘
                   │
                   ▼
    Claude Code receives "reason" as next instruction
            (loop repeats until COMPLETE)

Quick Start

1. Install the Hook

# Run the installation script
.claude/skills/autonomous-opus-loop/scripts/install.sh

Or manually add to .claude/settings.json:

{
  "hooks": {
    "Stop": [{
      "matcher": {},
      "hooks": [{
        "type": "command",
        "command": ".claude/skills/autonomous-opus-loop/scripts/autonomous-loop.sh"
      }],
      "timeout": 120
    }]
  }
}

2. Configure Your Objective

Create .claude/autonomous-config.json:

{
  "enabled": true,
  "objective": "Implement user authentication with JWT tokens",
  "success_criteria": [
    "All tests pass",
    "Code coverage > 80%",
    "No security vulnerabilities"
  ],
  "max_iterations": 30,
  "max_cost_usd": 15.00,
  "analyzer_model": "claude-sonnet-4-20250514",
  "verbose": true
}

3. Start Claude Code

# Start with initial task
claude -p "Begin implementing user authentication per the objective in .claude/autonomous-config.json"

Claude Code will now run autonomously until:

  • All success criteria are met
  • Max iterations reached
  • Cost limit exceeded
  • You manually interrupt (Ctrl+C)

Configuration Reference

Required Settings

Setting Type Description
enabled boolean Enable/disable autonomous mode
objective string High-level goal to achieve
success_criteria string[] Conditions that define "done"

Safety Limits

Setting Type Default Description
max_iterations number 50 Maximum loop iterations
max_cost_usd number 20.00 Maximum estimated cost
max_consecutive_failures number 3 Failures before escalation
max_runtime_minutes number 480 8-hour maximum runtime

Analyzer Settings

Setting Type Default Description
analyzer_model string claude-sonnet-4-20250514 Model for analysis
analyzer_max_tokens number 1024 Max tokens for analysis
include_full_transcript boolean false Send full vs. recent context
recent_messages_count number 10 Messages to include if not full

Behavior Settings

Setting Type Default Description
verbose boolean false Log detailed progress
notify_on_complete boolean true System notification on completion
save_session_log boolean true Save iteration history
escalation_mode string "pause" Action on escalation: pause/notify/abort

Operations

1. Enable Autonomous Mode

# Enable with default config
.claude/skills/autonomous-opus-loop/scripts/enable.sh

# Enable with specific objective
.claude/skills/autonomous-opus-loop/scripts/enable.sh \
  --objective "Refactor the payment module" \
  --max-iterations 20

2. Disable Autonomous Mode

.claude/skills/autonomous-opus-loop/scripts/disable.sh

3. Check Status

.claude/skills/autonomous-opus-loop/scripts/status.sh

Output:

Autonomous Loop Status
======================
Enabled: true
Objective: Implement user authentication with JWT tokens
Iterations: 12/30
Estimated Cost: $4.23/$15.00
Runtime: 45m/480m
Last Action: Implemented login endpoint
Next Action: Add password reset functionality
Status: RUNNING

4. View Session Log

.claude/skills/autonomous-opus-loop/scripts/view-log.sh

5. Emergency Stop

.claude/skills/autonomous-opus-loop/scripts/emergency-stop.sh

Safety Features

1. Doom Loop Prevention

The hook checks stop_hook_active flag to prevent infinite recursion:

if [ "$STOP_ACTIVE" == "true" ]; then
  # Already in a stop hook - allow termination
  exit 0
fi

2. Iteration Limits

Hard cap on iterations prevents runaway execution:

if [ "$ITERATION" -ge "$MAX_ITERATIONS" ]; then
  log "Max iterations ($MAX_ITERATIONS) reached"
  exit 0  # Allow stop
fi

3. Cost Tracking

Estimated cost monitoring based on token usage:

if (( $(echo "$TOTAL_COST > $MAX_COST" | bc -l) )); then
  log "Cost limit ($MAX_COST USD) exceeded"
  exit 0  # Allow stop
fi

4. Failure Detection

Consecutive failure tracking triggers escalation:

if [ "$CONSECUTIVE_FAILURES" -ge "$MAX_FAILURES" ]; then
  escalate "Doom loop detected: $CONSECUTIVE_FAILURES consecutive failures"
fi

5. Circular Work Detection

Semantic analysis detects repeated work patterns:

# Analyzer prompt includes:
"Detect if the same work is being repeated. If circular pattern detected, respond with ESCALATE."

Analyzer Prompts

Default Analyzer System Prompt

You are an autonomous development coordinator analyzing Claude Code progress.

OBJECTIVE: {objective}

SUCCESS CRITERIA:
{success_criteria}

Your task:
1. Analyze the recent work done
2. Check progress against success criteria
3. Decide: CONTINUE, COMPLETE, or ESCALATE

Response format:
- If more work needed: "CONTINUE: [specific next task with clear instructions]"
- If all criteria met: "COMPLETE: [summary of what was achieved]"
- If stuck/looping: "ESCALATE: [description of the problem]"

Be specific in CONTINUE responses. Give actionable next steps.
Do not repeat tasks that have already been completed.
Track what's done vs. what remains.

Custom Analyzer Prompts

Create custom prompts in .claude/autonomous-prompts/:

.claude/autonomous-prompts/
├── refactoring.txt      # For refactoring tasks
├── feature-build.txt    # For new features
├── bug-fix.txt          # For bug fixing
└── testing.txt          # For test writing

Reference in config:

{
  "analyzer_prompt_file": ".claude/autonomous-prompts/feature-build.txt"
}

Integration with Other Skills

With hooks-manager

The autonomous loop works alongside other hooks:

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": ".claude/skills/autonomous-opus-loop/scripts/autonomous-loop.sh"
      }]
    }],
    "PostToolUse": [{
      "tools": ["Write", "Edit"],
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write \"$FILE\""
      }]
    }]
  }
}

With agent-memory-system

Enable persistent learning across autonomous sessions:

{
  "integrations": {
    "agent_memory": true,
    "save_episodes": true,
    "learn_patterns": true
  }
}

With momentum-keeper

Combine for enhanced progress tracking:

{
  "integrations": {
    "momentum_keeper": true,
    "stall_detection": true,
    "energy_management": false
  }
}

With observability stack

Send metrics to your observability stack:

{
  "observability": {
    "enabled": true,
    "endpoint": "http://localhost:4317",
    "metrics": ["iterations", "cost", "duration", "success_rate"]
  }
}

Example Configurations

Overnight Feature Development

{
  "enabled": true,
  "objective": "Build complete user dashboard with charts, filters, and export",
  "success_criteria": [
    "Dashboard component renders without errors",
    "All 5 chart types implemented",
    "Filter functionality works",
    "Export to CSV and PDF works",
    "Unit tests pass with >80% coverage",
    "E2E tests pass"
  ],
  "max_iterations": 100,
  "max_cost_usd": 50.00,
  "max_runtime_minutes": 480,
  "analyzer_model": "claude-sonnet-4-20250514",
  "notify_on_complete": true,
  "escalation_mode": "notify"
}

Quick Refactoring Task

{
  "enabled": true,
  "objective": "Refactor utils/ to use TypeScript strict mode",
  "success_criteria": [
    "All files converted to .ts",
    "No 'any' types remain",
    "TypeScript compiles without errors",
    "All existing tests pass"
  ],
  "max_iterations": 20,
  "max_cost_usd": 10.00,
  "analyzer_model": "claude-sonnet-4-20250514"
}

Bug Hunting Session

{
  "enabled": true,
  "objective": "Find and fix the memory leak in the WebSocket handler",
  "success_criteria": [
    "Memory leak identified",
    "Root cause documented",
    "Fix implemented",
    "Memory usage stable over 1000 connections",
    "No regression in existing tests"
  ],
  "max_iterations": 30,
  "max_cost_usd": 15.00,
  "analyzer_prompt_file": ".claude/autonomous-prompts/bug-fix.txt"
}

Troubleshooting

Hook Not Firing

  1. Check hook is installed:

    cat .claude/settings.json | jq '.hooks.Stop'

  2. Verify script is executable:

    chmod +x .claude/skills/autonomous-opus-loop/scripts/*.sh

  3. Check for syntax errors:

    bash -n .claude/skills/autonomous-opus-loop/scripts/autonomous-loop.sh

Immediate Stop (Not Continuing)

  1. Check enabled is true in config
  2. Verify API key is set: echo $ANTHROPIC_API_KEY
  3. Check iteration/cost limits aren't exceeded
  4. Review logs: .claude/autonomous-log.jsonl

Infinite Loop / Runaway

  1. Emergency stop: Ctrl+C or run emergency-stop.sh
  2. Check stop_hook_active handling in script
  3. Verify max_iterations is reasonable
  4. Check for doom loop detection in logs

API Errors

  1. Verify API key: echo $ANTHROPIC_API_KEY | head -c 10
  2. Check model availability
  3. Review error in .claude/autonomous-log.jsonl
  4. Try with verbose: true for detailed output

Session Logs

All autonomous sessions are logged to .claude/autonomous-log.jsonl:

{"timestamp": "2024-01-15T10:30:00Z", "iteration": 1, "action": "START", "objective": "..."}
{"timestamp": "2024-01-15T10:31:00Z", "iteration": 1, "action": "CONTINUE", "task": "..."}
{"timestamp": "2024-01-15T10:35:00Z", "iteration": 2, "action": "CONTINUE", "task": "..."}
{"timestamp": "2024-01-15T11:00:00Z", "iteration": 15, "action": "COMPLETE", "summary": "..."}

View formatted:

.claude/skills/autonomous-opus-loop/scripts/view-log.sh --format pretty

Best Practices

1. Clear Objectives

Bad: "Make the code better" Good: "Refactor auth module to use dependency injection, add unit tests for all public methods"

2. Measurable Success Criteria

Bad: "Code should be clean" Good: "ESLint passes with no warnings, all functions have JSDoc comments"

3. Reasonable Limits

  • Start with lower iteration limits (20-30)
  • Increase based on task complexity
  • Set cost limits slightly above expected

4. Monitor First Runs

  • Use verbose: true initially
  • Watch the first few iterations
  • Adjust prompts based on behavior

5. Use Appropriate Models

  • claude-sonnet-4-20250514: Good balance of speed/quality (recommended)
  • claude-opus-4-5-20250929: Better analysis, higher cost
  • claude-3-5-haiku-20241022: Fast/cheap for simple tasks

Cost Estimation

Approximate costs per iteration (analyzer call):

Model Input (10k tokens) Output (1k tokens) Total
Sonnet 4 $0.03 $0.015 ~$0.045
Opus 4.5 $0.15 $0.075 ~$0.225
Haiku 3.5 $0.008 $0.004 ~$0.012

Example: 30 iterations with Sonnet = ~$1.35 for analyzer alone (Plus Claude Code usage costs)

References

  • references/hook-mechanics.md - Deep dive into Stop hook behavior
  • references/analyzer-prompts.md - Prompt engineering for analyzers
  • references/safety-patterns.md - Comprehensive safety documentation
  • references/integration-guide.md - Integrating with other skills

Scripts

  • scripts/autonomous-loop.sh - Main Stop hook handler
  • scripts/opus-analyzer.py - Python analyzer (alternative)
  • scripts/install.sh - Install hooks to settings
  • scripts/enable.sh - Enable autonomous mode
  • scripts/disable.sh - Disable autonomous mode
  • scripts/status.sh - Check current status
  • scripts/view-log.sh - View session logs
  • scripts/emergency-stop.sh - Emergency termination

Version History

  • v1.0.0 (2024-01): Initial release with Stop hook support
  • Supports bash and Python analyzers
  • Integration with observability stack
  • Comprehensive safety features
Weekly Installs
1
Repository
adaptationio/skrillz
Installed on
claude-code1