autonomous-opus-loop

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.

```

┌─────────────────────────────────────┐

│ 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)

```

1. Install the Hook

```bash

# Run the installation script

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

```

Or manually add to .claude/settings.json:

```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:

```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

```bash

# 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)

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 |

1. Enable Autonomous Mode

```bash

# 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

```bash

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

```

3. Check Status

```bash

.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

```bash

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

```

5. Emergency Stop

```bash

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

```

1. Doom Loop Prevention

The hook checks stop_hook_active flag to prevent infinite recursion:

```bash

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:

```bash

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:

```bash

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:

```bash

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:

```bash

# Analyzer prompt includes:

"Detect if the same work is being repeated. If circular pattern detected, respond with ESCALATE."

```

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:

```json

{

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

}

```

With hooks-manager

The autonomous loop works alongside other hooks:

```json

{

"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:

```json

{

"integrations": {

"agent_memory": true,

"save_episodes": true,

"learn_patterns": true

}

}

```

With momentum-keeper

Combine for enhanced progress tracking:

```json

{

"integrations": {

"momentum_keeper": true,

"stall_detection": true,

"energy_management": false

}

}

```

With observability stack

Send metrics to your observability stack:

```json

{

"observability": {

"enabled": true,

"endpoint": "http://localhost:4317",

"metrics": ["iterations", "cost", "duration", "success_rate"]

}

}

```

Overnight Feature Development

```json

{

"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

```json

{

"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

```json

{

"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"

}

```

Hook Not Firing

1. Check hook is installed:

```bash

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

```

1. Verify script is executable:

```bash

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

```

1. Check for syntax errors:

```bash

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

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

```json

{"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:

```bash

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

```

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

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/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/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

• v1.0.0 (2024-01): Initial release with Stop hook support
• Supports bash and Python analyzers
• Integration with observability stack
• Comprehensive safety features