automo

A plan → implement (parallel) → merge loop for agentic CLIs. Pick your harness (claude-code / codex / opencode / pi), point at three prompt files, and let it grind through your GitHub issues.

Install

npm install -g @dondragon2/automo

Requires git and the gh CLI to be authenticated.

You also need at least one supported harness installed and available on your $PATH:

| Harness | Install | |---|---| | claude-code | docs.anthropic.com/claude-code | | codex | npm install -g @openai/codex | | opencode | opencode.ai | | pi | pi.ai/talk |

Usage

The simplest invocation — bundled default prompts, repo auto-detected via gh repo view:

automo --harness codex --model gpt-5.5

Override anything you want:

automo \
  --harness claude-code \
  --model sonnet \
  --repo acme/widgets \
  --plan ./prompts/plan.md \
  --implement ./prompts/implement.md \
  --merge ./prompts/merge.md \
  --max-iterations 5

Flags

| Flag | Required | Default | Notes | |---|---|---|---| | --harness | yes | — | claude-code | codex | opencode | pi | | --plan | no | bundled prompts/plan.md | Plan prompt. {{REPO}} substituted. | | --implement | no | bundled prompts/implement.md | Placeholders: {{TASK_ID}}, {{ISSUE_TITLE}}, {{BRANCH}}, {{REPO}} | | --merge | no | bundled prompts/merge.md | Placeholders: {{BRANCHES}}, {{ISSUES}}, {{REPO}} | | --repo | no | gh repo view | GitHub repo as owner/name | | --model | no | per-harness default | Passed via the harness's model flag. For opencode, omit this to use your configured opencode/OpenRouter default. | | --max-iterations | no | 10 | Stops here or when plan returns no issues, whichever first | | --main-branch | no | main | Branch feature branches fork from; target of merges | | --log-dir | no | .automo-logs | Per-phase stdout/stderr logs | | --dry-run | no | false | Print spawn lines; touch no git, run no harness |

How it works

Each iteration runs three phases:

1. Plan — runs once on the main branch. The harness must output a <plan>{...}</plan> JSON block listing the issues to work on.
2. Implement — spawns one process per issue, all in parallel. Each job gets its own git worktree under .automo-worktrees/issue-<id>/ on its own branch, so concurrent agents never trample each other. A job is considered complete when its stdout contains <promise>COMPLETE</promise>.
3. Merge — checks out main, runs the merge prompt with {{BRANCHES}} and {{ISSUES}} filled in (completed jobs only), then removes each merged worktree.

Logs land in --log-dir as iter-N-plan.log, iter-N-impl-<id>.log, iter-N-merge.log.

Bundled prompts

The package ships three default prompts:

• plan.md — analyzes open GitHub issues labeled Automo and outputs a dependency-aware plan
• implement.md — pulls an issue, works in a red-green-refactor cycle, runs typecheck/tests, commits with AUTOMO: prefix
• merge.md — merges branches, resolves conflicts, closes issues

Override any of them with the corresponding flag if your workflow differs.

Resume / interruption

Worktrees and branches are reused if they already exist — killing and restarting picks up where it left off. Jobs that didn't emit <promise>COMPLETE</promise> are skipped during merge and will reappear in the next plan if still open.

Dry run

automo --harness claude-code --dry-run

Prints what would happen, fabricates a single fake issue so you can see the loop flow, doesn't touch git or spawn the harness.