autoclaude/autocode.md

Autoclaude - Autonomous Claude Code Control System

Overview

Autoclaude is a professional-grade autonomous multi-agent control system designed to manage and orchestrate Claude Code sessions. It provides autonomous monitoring, prompt handling, and session management capabilities through a clean command-line interface.

Project Information

• Name: Autoclaude
• Version: 2.1.0
• Author: Retoor (retoor@molodetz.nl)
• License: MIT
• Status: Production Beta
• Repository: https://github.com/retoor/autoclaude

Architecture

Design Philosophy

Autoclaude follows strict engineering principles:

1. YAGNI - Add only what is needed now, not for hypothetical futures
2. DRY - Single source of truth for patterns and logic
3. CONSISTENT - Uniform patterns and styles throughout
4. KISS - Simplicity over complexity
5. OO - Object-oriented design when appropriate

Core Components

The system comprises modular components working in concert:

• cli.py: Command-line interface and session management
• orchestrator.py: Multi-agent orchestration engine
• multi_agent_system.py: Agent spawning and lifecycle management
• utils.py: Shared utility functions and helpers
• __init__.py: Package initialization and version management

System Flow

1. User invokes autoclaude CLI command
2. CLI processes command and interacts with tmux sessions
3. Service commands trigger orchestrator startup
4. Orchestrator spawns specialized agents for monitoring
5. Agents continuously analyze session state
6. Auto-approval mechanisms handle prompts autonomously
7. Status commands report orchestration state

Functionality

Core Capabilities

Session Detection and Management

• Automatic detection of Claude Code sessions in tmux
• Pattern-based identification using configurable regex patterns
• Support for multiple concurrent sessions
• Real-time session state monitoring

Autonomous Prompt Handling

• Pattern-based prompt detection
• Automatic approval of known prompt types
• Support for custom approval responses
• Non-intrusive monitoring without user disruption

Multi-Agent Orchestration

• Specialized monitor agents for each session
• Control agents for directive execution
• Analysis agents for state evaluation
• Coordinator agents for inter-agent communication

Configuration and State Management

• JSON-based configuration files
• Runtime target configuration via CLI
• State persistence in /tmp/claude_auto/
• Configuration hot-reload capability

CLI Usage

Installation

From the autoclaude directory:

pip install -e .

This installs the autoclaude command system-wide.

Command Reference

General Commands:

• autoclaude - Interactive menu
• autoclaude help - Show help message
• autoclaude version - Show version

Session Commands:

• autoclaude list - List detected Claude Code sessions
• autoclaude monitor - Monitor session in real-time
• autoclaude send - Send command to session
• autoclaude approve - Approve prompt in session

Service Commands:

• autoclaude start - Start orchestrator (auto-detect mode)
• autoclaude start - Start monitoring specific session
• autoclaude start toggle - Toggle automation for active pane
• autoclaude stop - Stop all monitoring
• autoclaude stop - Stop monitoring specific session
• autoclaude status - Check orchestrator status
• autoclaude logs - Follow orchestrator logs

Setup Commands:

• autoclaude --install-shortcut - Install Ctrl+A+A keyboard shortcut in tmux config

Usage Examples

Detect all Claude Code sessions:

autoclaude list

Start monitoring a specific panel:

autoclaude start main 8

Monitor session in real-time:

autoclaude monitor main 2

Send a command to a session:

autoclaude send main 2 "make test"

Check orchestrator status:

autoclaude status

Install keyboard shortcut:

autoclaude --install-shortcut

Toggle automation for active pane:

autoclaude start toggle
# Or use keyboard shortcut in tmux: Ctrl+A+A

View live logs:

autoclaude logs

Configuration

Config File Structure

File: config.json

{
  "version": "2.1.0",
  "orchestrator": {
    "enabled": true,
    "interval": 2,
    "max_agents": 10
  },
  "auto_approve": true,
  "auto_control": true
}

Configuration Fields:

• orchestrator.interval: Monitoring check interval in seconds
• orchestrator.max_agents: Maximum concurrent agents
• auto_approve: Enable automatic prompt approval
• auto_control: Enable automatic control directives

Runtime Targets

File: /tmp/claude_auto/targets.json

Dynamically created by CLI when adding targets:

{
  "targets": {
    "main": [2, 8],
    "secondary": [3]
  }
}

Detection Patterns

Pattern Matching

Autoclaude uses regex patterns to identify Claude Code panes. All patterns are centralized in two places: TmuxHelper.is_claude_pane() in cli.py and ClaudeOrchestrator.is_claude_pane() in orchestrator.py.

Core Patterns:

• r'⏵⏵.*\b' - Auto mode indicator
• r'Do you want to proceed' - Approval prompt
• r'Agent\s+(finished|running)\b' - Agent status
• r'※ recap:' - Recap indicator
• r'❯\s*\d+.' - Selection menu

Adding New Patterns

When Claude Code UI changes, add patterns to the detection methods:

1. Update TmuxHelper.is_claude_pane() in cli.py
2. Update ClaudeOrchestrator.is_claude_pane() in orchestrator.py
3. Test with: autoclaude list
4. Verify no false positives with: python3 -c "from autoclaude import multi_agent_system"

False Positive Prevention

Python logging timestamps are filtered via:

if re.search(r'\[\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}', content):
    return False

This prevents monitoring agent output from being detected as Claude Code sessions.

Development Guidelines

Code Organization

Package Structure:

autoclaude/
  src/autoclaude/
    __init__.py
    cli.py
    orchestrator.py
    multi_agent_system.py
    utils.py
  pyproject.toml
  autocode.md
  tests/
  docs/

Coding Standards

Type Hints: All public functions should include type hints Docstrings: One-line docstrings only; avoid multi-line blocks Comments: Only for non-obvious WHY, never WHAT Line Length: Maximum 100 characters Naming: snake_case for functions/variables, PascalCase for classes

Adding Features

Process for adding new functionality:

1. Identify need and verify no existing solution
2. Follow YAGNI principle - add only what is needed
3. Maintain DRY - use existing classes where possible
4. Keep code CONSISTENT with existing patterns
5. Keep implementation KISS - prefer simple over complex
6. Use OO appropriately - classes for stateful operations only
7. Update autocode.md to document the feature
8. Create commit with clear message

Testing Requirements

All new code should:

• Compile without syntax errors: python3 -m py_compile
• Follow existing patterns (no new abstractions)
• Not introduce new dependencies
• Pass basic functionality test with CLI

Version Management

Version Numbering

Format: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes to config or behavior
• MINOR: New features, new patterns, improvements
• PATCH: Bug fixes, logging improvements

Updating Version Numbers

Update in these files for each release:

• pyproject.toml: version field
• src/autoclaude/__init__.py: version
• src/autoclaude/cli.py: version
• src/autoclaude/orchestrator.py: version
• autocode.md: Project Information section

Release Process

For patch releases (2.1.0 to 2.1.1):

1. Fix bug or improve code
2. Update version in all files
3. Test thoroughly: autoclaude list, autoclaude start, etc.
4. Commit with message: "Fix: [description]. Bump to 2.1.1"

For minor releases (2.1.0 to 2.2.0):

1. Implement feature following all guidelines
2. Update version in all files
3. Test end-to-end
4. Commit with message: "Feature: [name]. Bump to 2.2.0"

For major releases (2.0.0 to 3.0.0):

1. Implement breaking changes
2. Create MIGRATION.md with upgrade instructions
3. Update version in all files
4. Commit with clear explanation of breaking changes

Commit Message Format

All commits should include Co-Author attribution:

[type]: [description]. Bump to X.Y.Z

[Detailed explanation of changes if needed]

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Types: feat, fix, chore, docs, test, refactor

Specifications and Requirements

System Requirements

• Python 3.7 or higher
• tmux (any recent version)
• POSIX-compatible operating system (Linux, macOS)
• /tmp directory with write permissions

Dependencies

Core dependencies (defined in pyproject.toml):

• Standard library only - no external packages required

Development dependencies:

• pytest for testing
• black for code formatting
• flake8 for linting
• mypy for type checking

Performance Specifications

• Session detection: under 5 seconds for 10+ sessions
• Monitoring loop interval: 2 seconds (configurable)
• Memory usage: under 50MB for typical deployments
• CPU usage: minimal when idle (< 1% average)

Security Specifications

• No credentials stored in configuration files
• No external network communication
• Local socket/tmux communication only
• No elevated privileges required (user-level operation)
• Configuration files use standard JSON (text-based, auditable)

Reliability Specifications

• Graceful error handling - system continues on single session failures
• Process crash recovery - orchestrator can restart
• State persistence - targets maintained across restarts
• Log retention - rotating logs to prevent disk fill

Maintenance Operations

Regular Tasks

Daily: Verify orchestrator running and monitoring targets Weekly: Check for new Claude Code UI patterns Monthly: Review logs for errors or issues Quarterly: Update documentation if Claude Code changes

Troubleshooting

Orchestrator not starting:

1. Check tmux availability: tmux -V
2. Verify Python 3.7+: python3 --version
3. Check state directory: ls -la /tmp/claude_auto/
4. View logs: cat /tmp/claude_auto/orchestrator.log

Sessions not detected:

1. List tmux sessions: tmux list-sessions
2. Manually capture pane: tmux capture-pane -t main:0 -p
3. Verify pattern matches: grep -E "⏵⏵|Do you want"
4. Run diagnostics: python3 -c "from autoclaude.cli import TmuxHelper; print(TmuxHelper.is_claude_pane(open('/tmp/test.txt').read()))"

Prompts not auto-approved:

1. Check auto_approve enabled in config.json
2. Verify detection: autoclaude list should show sessions
3. Check orchestrator running: autoclaude status
4. Review logs: autoclaude logs | grep "Auto-approving"

Monitoring and Logs

Log Locations:

• Orchestrator: /tmp/claude_auto/orchestrator.log
• PID file: /tmp/claude_auto/orchestrator.pid
• Targets: /tmp/claude_auto/targets.json

Log Format:

[2026-09-16 15:30:45,123] INFO: Message text
[2026-09-16 15:30:46,234] ERROR: Error description

Follow logs in real-time:

autoclaude logs

Documentation Standards

Writing Standards

All documentation follows professional, precise writing standards:

• Active voice preferred
• Concise, direct sentences
• No promotional language
• No contributor solicitation
• No emoji or decorative elements
• Consistent terminology throughout

File Organization

Documentation files:

• autocode.md: Complete system documentation
• README.md: Quick start and overview (if needed)
• Installation instructions in pyproject.toml metadata

Keeping Documentation Current

Documentation updates required when:

• Version changes (update version numbers)
• New features added (document in relevant sections)
• New patterns added (update Detection Patterns section)
• Configuration changes (update Configuration section)
• CLI commands change (update CLI Usage section)

Future Enhancements

Potential improvements for future versions:

• Configuration hot-reload without restart
• Alternative session backends (screen, etc.)
• Advanced approval rules engine
• Metrics export (Prometheus format)
• Remote management capabilities
• Enhanced error recovery mechanisms
• Session state snapshots and recovery

Frequently Asked Questions

Q: Does Autoclaude modify Claude Code? A: No. Autoclaude only reads pane content and sends keyboard input. It cannot modify Claude Code files or settings.

Q: Can I run multiple orchestrator instances? A: Only one orchestrator should run at a time per machine. Use targets to monitor multiple sessions with one orchestrator.

Q: What happens if orchestrator crashes? A: Restart with autoclaude start. Targets persist in /tmp/claude_auto/targets.json and will be restored.

Q: Can I configure custom approval responses? A: Yes, edit config.json and restart orchestrator. Patterns and responses follow the ResponseStrategy class.

Q: How do I prevent false prompt detection? A: Review patterns in is_claude_pane() methods. Add exclusions if needed. Test with actual pane content.

Support and Issues

For issues, questions, or feature requests:

1. Check autocode.md troubleshooting section
2. Review error messages in autoclaude logs
3. Verify system requirements are met
4. Check for matching patterns in pane content

Last Updated: 2026-09-16 Version: 2.1.0