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:

```bash
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 <session> <window> - Monitor session in real-time
- autoclaude send <session> <window> <command> - Send command to session
- autoclaude approve <session> <window> - Approve prompt in session

Service Commands:
- autoclaude start - Start orchestrator (auto-detect mode)
- autoclaude start <session> <window> - Start monitoring specific session
- autoclaude start toggle - Toggle automation for active pane
- autoclaude stop - Stop all monitoring
- autoclaude stop <session> <window> - 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:
```bash
autoclaude list
```

Start monitoring a specific panel:
```bash
autoclaude start main 8
```

Monitor session in real-time:
```bash
autoclaude monitor main 2
```

Send a command to a session:
```bash
autoclaude send main 2 "make test"
```

Check orchestrator status:
```bash
autoclaude status
```

Install keyboard shortcut:
```bash
autoclaude --install-shortcut
```

Toggle automation for active pane:
```bash
autoclaude start toggle
# Or use keyboard shortcut in tmux: Ctrl+A+A
```

View live logs:
```bash
autoclaude logs
```

## Configuration

### Config File Structure

File: config.json

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

```json
{
  "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:
```python
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 <file>
- 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:
```bash
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