ACE - Overseer

One command to provision a worktree, open a tmux window, and start working on a task. ACE Logo

Gem Version Ruby License: MIT

Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.

Getting Started | Usage Guide | Handbook - Skills, Agents, Templates

ace-overseer demo

Starting task work means creating a worktree, opening a tmux window, and preparing an assignment - three manual steps before you even begin coding. ace-overseer collapses that into a single command, tracks what is running where, and cleans up finished worktrees so nothing lingers. You can jump straight to a focused worktree any time with a single invocation.

How It Works

  1. Resolve task refs and create a scoped worktree.
  2. Route assignment creation through ace-assign create --task ..., which expands the assignment preset into concrete steps under .ace-local/assign/, then open a dedicated tmux window mapped to that worktree.
  3. Instruct the agent inside the tmux window to act as an orchestrator and drive the assignment step-by-step.

Use Cases

Kick off task work - provisions an isolated worktree via ace-git-worktree, opens a dedicated ace-tmux window, and prepares an ace-assign assignment - all in one shot. Supports regular tasks and subtask trees. Draft tasks are blocked until reviewed. Use /as-overseer or from the CLI:

ace-overseer work-on --task 8q4 --preset work-on-task

Bundle related tasks - pass multiple task refs or a task with subtasks and they all land in a single worktree. The refs are expanded and forwarded to the assignment preset, so every step for every task is prepared in one assignment. Drive through them with /as-assign-drive.

Monitor active work - ace-overseer status shows a dashboard of all task worktrees with assignment progress, git state, and PR links. Add --watch for a live-refreshing view that updates assignments every 15 seconds and git status every 5 minutes.

ace-overseer status --watch

Clean up finished work - ace-overseer prune removes completed worktrees safely. It checks three conditions before removing: assignment completed, task marked done, and git working tree clean. Use --dry-run to preview what would be pruned, --force for worktrees that fail safety checks, or --assignment to prune a single stale assignment.

Customize the workflow - the full pipeline is defined in two layers: the assignment preset controls which steps run and in what order (onboard, implement, test, release, review, PR), while each step references a workflow instruction that defines how it executes. Browse available presets or create your own to tailor the pipeline to your project.

For explicit end-to-end validation paths, see Public Verification Paths.

Testing

  • ace-test ace-overseer runs deterministic fast coverage from test/fast/.
  • ace-test ace-overseer feat runs deterministic feature coverage from test/feat/ when present.
  • ace-test ace-overseer all runs fast + feat deterministic coverage.
  • ace-test-e2e ace-overseer runs retained workflow scenarios from test/e2e/.

The package no longer uses deterministic *_test.rb files under test/e2e/ and does not use ace-test ace-overseer e2e as a deterministic test path.

Getting Started | Usage Guide | Handbook - Skills, Agents, Templates | Part of ACE