Guides
Auto-Mode: Autonomous Development Loops
Let Autohand work autonomously on your tasks through iterative improvement cycles. Hands-free coding with built-in safety limits.
Experimental
The Ralph Wiggum Mode
"I'm helping!"
Auto-mode is our implementation of the Ralph technique. Like Ralph confidently declaring he's helping, the AI agent keeps trying until it gets things right. Each iteration, however clumsy, brings you closer to the goal. Embrace the chaos, tune the prompts, and let the loop do its thing.
Persistent goals Experimental
/goal adds a durable objective layer for longer loops that should survive ordinary prompts, queued work, JSON-RPC clients, ACP clients, and hook-driven automation.
This surface is behind the slash_goal feature flag while it is experimental.
Goal state tracks the active objective, queue, status, elapsed time, token usage, optional budgets, and completion floors. Agents can inspect or update that state through the goal tools only after the feature flag is enabled.
Overview
When you enable auto-mode, Autohand enters a self-referential feedback loop:
- The agent works on your task
- After each iteration, it reviews its previous work (git history, file changes, test results)
- It continues improving until the task is complete or limits are reached
- Changes are optionally isolated in a git worktree for safety
Quick start
How it works
CLI usage
Options
| Option | Description | Default |
|---|---|---|
--max-iterations <n> | Maximum loop iterations | 50 |
--completion-promise <text> | Text marker signaling completion | "DONE" |
--no-worktree | Disable git worktree isolation | - |
--checkpoint-interval <n> | Git commit every N iterations | 5 |
--max-runtime <m> | Maximum runtime in minutes | 120 |
--max-cost <d> | Maximum API cost in dollars | 10 |
--dry-run | Preview actions without executing | - |
Examples
Slash commands
From interactive mode:
| Command | Description |
|---|---|
/automode <prompt> | Start auto-mode with a task |
/automode status | Show current loop state |
/automode pause | Pause the loop |
/automode resume | Resume paused loop |
/automode cancel | Cancel the loop |
/automode help | Show help |
Examples
Writing good prompts
Include clear completion criteria in your prompts:
Bad example
Good example
The <promise>DONE</promise> marker tells auto-mode that the task is complete.
Cancellation
Multiple ways to stop an auto-mode loop:
| Method | How |
|---|---|
| ESC Key | Press ESC during the loop |
| Slash Command | /automode cancel |
| Hooks | Trigger automode:cancel event |
| RPC | Call automode.cancel method |
| Ctrl+C | Hard stop (exits immediately) |
Safety features
Resource limits
| Limit | Default | Purpose |
|---|---|---|
| Max Iterations | 50 | Prevents infinite loops |
| Max Runtime | 120 min | Limits total time |
| Max Cost | $10 | Caps API spending |
| Checkpoint Interval | 5 | Creates git checkpoints |
Git worktree isolation
By default, auto-mode creates an isolated git worktree:
- Branch:
autohand-automode-<timestamp> - Worktree:
/tmp/autohand-worktree-<hash>
Benefits:
- Your main branch is protected
- Changes can be reviewed before merging
- Easy to discard if something goes wrong
On success, changes are merged back to your original branch.
Circuit breaker
Auto-mode includes a circuit breaker that stops the loop when:
- No Progress: 3 consecutive iterations with no file changes
- Same Errors: 5 consecutive iterations with identical error output
- Test Loop: 3 consecutive iterations only running tests (no code changes)
This prevents getting stuck in unproductive loops.
State file
Auto-mode maintains state in .autohand/automode.local.md:
Changelog generation
After each session, auto-mode generates AUTOMODE_CHANGELOG.md:
Hook events
Auto-mode emits events that can trigger hooks:
| Event | When |
|---|---|
automode:start | Loop started |
automode:iteration | Each iteration |
automode:checkpoint | Git commit made |
automode:pause | Loop paused |
automode:resume | Loop resumed |
automode:cancel | Loop cancelled |
automode:complete | Loop completed successfully |
automode:error | Error occurred |
Example hook
Configuration
Add defaults to ~/.autohand/config.json:
Tips
- Include clear completion criteria in your prompt
- Use
<promise>DONE</promise>to signal completion - Press ESC at any time to cancel
- Use
/automode statusto check progress - Review the changelog after each session
- Start with smaller tasks to understand the behavior
- Enable worktree isolation (default) for safety
- Set appropriate limits to control cost and time
Troubleshooting
Loop does not complete
- Check if your prompt has clear completion criteria
- Verify the completion marker matches your config
- Look for stuck patterns (circuit breaker should catch these)
Worktree creation fails
- Ensure you are in a git repository
- Check for uncommitted changes
- Use
--no-worktreeto disable isolation
High cost
- Lower
--max-iterations - Set a stricter
--max-cost - Use a more efficient model
- Break task into smaller chunks
Loop appears stuck
- The circuit breaker should auto-trigger
- Press ESC to cancel manually
- Check
.autohand/automode.local.mdfor state
Frequently asked questions
What is auto-mode in Autohand CLI?
Auto-mode is an autonomous development feature that lets Autohand work through multi-step tasks without manual approval at each step. The agent plans, writes code, runs tests, and iterates until the task is complete. Built-in safety rails include iteration limits, cost caps, runtime limits, and git worktree isolation.
How do I start auto-mode?
From the command line, run autohand --auto-mode 'build a REST API with user authentication'. Inside an interactive session, type /automode followed by your task. You can also start auto-mode from the slash command without a prompt and describe the task when asked.
How do I set cost and time limits for auto-mode?
Use --max-cost to set a dollar limit (default $10), --max-runtime for minutes (default 120), and --max-iterations for loop count (default 50). Example: autohand --auto-mode 'refactor auth' --max-cost 5 --max-iterations 20 --max-runtime 30. These limits also work with the /automode slash command.
Is auto-mode safe to use?
Auto-mode includes multiple safety features. Changes run in an isolated git worktree by default so your main branch is untouched. A circuit breaker stops the loop after repeated failures. Configurable cost, iteration, and runtime limits prevent runaway spending. You can pause or cancel at any time with /automode pause or /automode cancel.