Automode Mechanics
Relevant source files
The following files were used as context for generating this wiki page:
Automode is an autonomous development feature within the Autohand CLI that enables the agent to work through iterative improvement cycles without constant user intervention. Inspired by the "Ralph technique," it orchestrates complex tasks by managing stateful iterations, implementing safety circuit breakers, and providing isolated environments via Git worktrees. Sources: src/commands/automode.ts:101-103, src/core/AutomodeManager.ts:13-17
The system is designed to handle multi-step software engineering tasks—such as building APIs or refactoring modules—by defining clear completion criteria and monitoring for progress or repetitive errors. Sources: src/commands/automode.ts:145-148, src/core/AutomodeManager.ts:153-157
Core Architecture
The Automode system is built around the AutomodeManager, which acts as the primary orchestrator. It coordinates between the agent's execution loop, the filesystem state, and Git-based isolation mechanisms. Sources: src/core/AutomodeManager.ts:54-70
Component Relationship
The diagram above illustrates the relationship between the central manager and its supporting utility classes for state tracking and reporting. Sources: src/core/AutomodeManager.ts:54-85, src/core/AutomodeState.ts:24-34
State Management and Persistence
Automode maintains persistent state in a specific file: .autohand/automode.local.md. This file tracks the current iteration, session ID, file mutation metrics, and Git metadata. Sources: src/core/AutomodeState.ts:16, src/core/AutomodeState.ts:52-67
Session State Attributes
| Field | Type | Description |
|---|---|---|
sessionId | string | Unique identifier for the autonomous session. |
status | string | Current state: running, paused, completed, cancelled, or failed. |
currentIteration | number | The index of the current loop cycle. |
maxIterations | number | Maximum allowed cycles before forced termination. |
filesCreated | number | Total count of new files added during the session. |
filesModified | number | Total count of existing files edited. |
completionPromise | string | Text marker used to signal task completion (default: "DONE"). |
Sources: src/types.ts:149-178, src/core/AutomodeState.ts:52-67
The Autonomous Loop
The execution flow involves a series of guarded iterations. Each iteration executes a task prompt, captures file changes, and evaluates the environment against safety constraints. Sources: src/core/AutomodeManager.ts:121-225
Execution Flow Diagram
Automode utilizes a "Circuit Breaker" to prevent infinite loops or repetitive failures. It monitors for three specific conditions: lack of file changes, identical error hashes across iterations, and excessive test-only cycles. Sources: src/core/AutomodeManager.ts:141-213, src/core/AutomodeState.ts:145-190
Environment Isolation and Checkpointing
To ensure safety during autonomous operations, the system supports Git Worktree isolation. This allows the agent to work in a separate directory on a dedicated branch, preventing interference with the user's primary working directory. Sources: src/core/AutomodeManager.ts:405-430
- Worktree Setup: Creates a temporary directory and a new branch (e.g.,
autohand-automode-[timestamp]). Sources: src/core/AutomodeManager.ts:413-418 - Checkpointing: At defined intervals (default: 5 iterations), the manager stages all changes and creates a Git commit. Sources: src/core/AutomodeManager.ts:435-470
- Merging: Upon successful completion, the worktree branch is merged back into the original branch. Sources: src/core/AutomodeManager.ts:480-505
Completion and Reporting
When a session ends, the system performs cleanup and provides detailed documentation of the autonomous work. Sources: src/core/AutomodeManager.ts:534-555
Automode Changelog
A session report (AUTOMODE_CHANGELOG.md) is generated containing a summary of the task, duration, cost estimation, and a step-by-step log of actions performed in every iteration. Sources: src/core/AutomodeChangelog.ts:38-70
Project Metadata Updates
The AgentsMdUpdater automatically injects discovered patterns (tech stack, commands, framework) into the AGENTS.md file. This ensures that the results of the autonomous session inform future agent interactions. Sources: src/core/AgentsMdUpdater.ts:32-55, src/core/AutomodeManager.ts:333-345
// Example of pattern detection results being stored in AGENTS.md
const sectionContent = `## Tech Stack\n\n${techStackContent}\n`;
return this.updateSection(content, 'Tech Stack', sectionContent);
Sources: src/core/AgentsMdUpdater.ts:74-78
Summary
Automode Mechanics provide a robust framework for unsupervised task execution. By combining persistent state tracking, automated Git checkpoints, and heuristic circuit breakers, the system balances high autonomy with development safety and transparency. Sources: src/core/AutomodeManager.ts:13-25, src/core/AutomodeState.ts:145-150