agent-ops-cli

AO — Agent Ops CLI

AO is a development operations system for humans and autonomous agents. It combines event-sourced issue tracking, deterministic automation, worktree-first execution, and a web Kanban UI into one workflow.

Why AO

AO is designed for teams that want to:

• capture and execute work quickly
• reduce merge conflicts through explicit workflow expectations
• maintain durable, replayable issue history
• support both human and agent execution with the same commands

In short: project memory + execution workflow + agent ergonomics.

What's New (latest additions)

Web UI workflow improvements

• Top-level tabs split the interface into:
  • Kanban Board
  • Branch Worktrees
• Single Workflow field in issue create/edit:
  • No special workflow requirements (default)
  • Separate worktree required
  • Stacked diffs preferred
  • Stacked diffs + separate worktree
• Workflow helper text now updates dynamically under the dropdown.
• Branch Worktree launch default now prefers Editor (config) automatically.
• Force remove worktree action with confirmation for destructive cleanup.

Code host integration (Gitea + GitHub)

• CodeHost abstraction — ao stack push works with both GitHub and Gitea via a unified provider layer.
• Gitea support — local Gitea instance via docker-compose.yml for integration testing.
• Environment-based provider selection — set CODE_HOST_TARGET=gitea and CODE_HOST_TOKEN to switch providers.
• Graceful fallback — when no token is configured, stack commands fall back to the gh CLI.

Versioning behavior

• Issue version defaults from .version when omitted.
• For Python projects, .version must match pyproject.toml project.version.
• Added ao version commands for synchronized version updates.

UI overview

Kanban tab

Use this for triage, assignment, and status/priority movement.

Branch Worktrees tab

Use this for isolated branch workspaces, launcher actions, and git worktree operations.

Install

Tool install (recommended)

uv tool install agent-ops-cli
ao --version

Local development checkout

git clone <repo-url>
cd agent-ops
uv sync
uv tool install .
ao --version

ao ... examples below assume AO is installed as a tool. Use uv run ... for development commands (tests/lint/build).

Quick start

Human flow

ao add "Implement feature flag support" --type feat --priority high
ao next
ao ls --view kanban
ao gate

Agent/automation flow (JSON)

ao add "Fix timeout regression" --type bug --priority high
ao ls --status todo --limit 20
ao next

Profiles (personal context + workspace preferences)

AO profiles let you keep reusable personal metadata and per-profile preferences, then apply them consistently across repositories and agent workflows.

When profiles are useful

• You work across multiple identities (personal/client/internal).
• You want deterministic .env materialization for common variables.
• You want a separate preferences file per profile with workspace sync.

Typical profile workflow

ao profile init my-main \
  --full-name "Jane Doe" \
  --email "jane@example.com" \
  --github-username "janedoe" \
  --website "https://example.com" \
  --editor code \
  --var TEAM=platform \
  --var AO_MODE=agent

ao profile ls
ao profile use my-main
ao profile show

Update profile fields and vars

ao profile set my-main --var TEAM=core --var LANG=python --unset-var AO_MODE
ao profile show my-main

Apply profile data into .env

ao profile env apply my-main .env

This writes/updates keys like FULL_NAME, EMAIL, GITHUB_USERNAME, optional WEBSITE, and any custom --var entries.

Profile preferences commands

ao profile prefs open my-main
ao profile prefs sync my-main

prefs open opens the profile preferences markdown in your configured editor. prefs sync keeps home and workspace preference files aligned (newest wins).

Worktree + stacked-diff guide

This is the recommended model for parallel, low-conflict execution.

Workflow modes in issues

Example 1: Small standalone bug fix (no special workflow)

Use this when scope is tiny and independent.

ao add "Fix typo in API error" --type bug --priority low
ao next
ao gate
ao close BUG-0001@abc123 --log "Fixed and verified"

Example 2: Isolated risky change (separate worktree required)

Use this when local changes may conflict with ongoing work.

ao add "Refactor event parser" --type refac --priority medium --separate-worktree required
ao worktree add --epic parser --step 1 --summary refactor-core --open editor
ao worktree ls

Example 3: Feature split into reviewable layers (stacked diffs preferred)

Use this when one feature is best reviewed as sequential pieces.

ao add "Add notifications feature" --type feat --priority high --stacked-diff yes
ao worktree plan --epic notifications --max-files 6 --max-loc 300
ao worktree add --epic notifications --step 1 --summary schema
ao worktree add --epic notifications --step 2 --summary api
ao worktree add --epic notifications --step 3 --summary ui

Example 4: Full isolation + stacked delivery

Use this for high-risk or long-running epics.

ao add "Migrate auth subsystem" --type feat --priority high --stacked-diff yes --separate-worktree required
ao worktree plan --epic auth
ao worktree add --epic auth --step 1 --summary bootstrap --open opencode
ao worktree land --epic auth
ao worktree land --epic auth --final --target main --ci-green --approved

Branch Worktrees tab usage (practical)

1. Open Branch Worktrees tab.
2. Confirm source branch and discovered worktrees.
3. Choose launcher (defaults to Editor) and click Open.
4. Choose a git action from Git action... and click Run.
5. For Force remove, confirm the safety prompt.

Troubleshooting quick hits

• Launcher unavailable: install tool or use Editor.
• Protected branch blocked: switch to non-protected integration branch.
• Worktree remove fails: retry with Force remove only when safe.

For complete policy, recovery, and gate semantics: see docs/worktree-stacked.md.

Core CLI capabilities

Issue lifecycle

ao add "Fix timeout regression" --type bug --priority high
ao show BUG-0001@abc123
ao set BUG-0001@abc123 --status in_progress --owner alice
ao close BUG-0001@abc123 --log "Validated and merged"

Event-sourced state

ao event append --in -
ao rebuild
ao ls --view summary

Prioritization and execution

ao next --limit 10
ao ls --view kanban
ao stale --days 7
ao triage

Dependencies and planning

ao link add BUG-0004@aaaaaa --depends-on FEAT-0012@bbbbbb
ao link graph --graph-format mermaid
ao dep-tree BUG-0004@aaaaaa --depth 5

Acceptance criteria and gates

ao ac add BUG-0004@aaaaaa "Timeout test passes under load"
ao ac check BUG-0004@aaaaaa 1
ao validate
ao gate BUG-0004@aaaaaa

Focus and handoff

ao focus set-doing BUG-0004@aaaaaa --task "Patch retry strategy"
ao focus set-next "Run validation and close if gate passes"
ao focus sync

Hooks and automation

ao hooks install
ao hooks status
ao hooks agent-install --engine copilot
ao hooks loop-prompt --engine copilot
ao hooks loop-run --engine copilot --max 5

For an end-to-end guide to testing the standalone GitHub Copilot CLI autonomous loop, see docs/copilot-autonomous-loop.md.

Workers and assignment

ao worker add reviewer --engine copilot --model gpt-5.3-codex
ao worker assign BUG-0004@aaaaaa --worker reviewer
ao worker ls

References and traceability

ao ref init BUG-0004@aaaaaa
ao ref status BUG-0004@aaaaaa
ao ref open BUG-0004@aaaaaa

Reporting and export

ao export json --out reports/issues.json
ao export jsonl --out reports/issues.jsonl
ao bench rebuild --events data/events.jsonl

Web UI

ao web --host 127.0.0.1 --port 8042

Versioning and release management

Issue version metadata (.version)

• If issue version is omitted, AO defaults from .version.
• Python projects require .version == pyproject.toml project.version.
• Non-Python projects use .version as source-of-truth when present.

Project version command

• ao version set X.Y.Z
• ao version bump patch|minor|major
• ao version ... --dry-run to preview file updates

You can also configure extra replacement targets in pyproject.toml: [[tool.ao.version.targets]] with path, pattern, and replace.

Code host integration

AO supports both GitHub and Gitea as code hosts for pull request operations in stacked-diff workflows.

Configuration

Set environment variables to select a provider:

# GitHub (default)
export CODE_HOST_TOKEN="ghp_..."

# Gitea
export CODE_HOST_TARGET=gitea
export CODE_HOST_TOKEN="your-gitea-token"
export CODE_HOST_BASE_URL="http://localhost:3000/api/v1"  # optional, defaults to localhost

Or configure via ~/.ao/config.json:

{
  "code_host": {
    "target": "gitea",
    "token": "your-token",
    "base_url": "http://localhost:3000/api/v1"
  }
}

When no token is configured, ao stack push falls back to the gh CLI.

Local Gitea for testing

A docker-compose.yml is provided at the project root:

docker compose up -d     # Start Gitea on localhost:3000
docker compose down      # Stop

This creates a local Gitea instance with SQLite storage and an admin user, ready for integration testing.

Architecture at a glance

• events.jsonl — append-only event history
• active.jsonl — derived active snapshot
• src/ao/cli.py — command routing and UX
• src/ao/api.py — programmatic API client
• src/ao/_internal/ — internal implementation modules
• src/ao/_internal/codehost.py — GitHub/Gitea provider abstraction
• src/ao/web/ — web UI + API endpoints

Skills and prompts

• Skills live in .ao/skills/
• Prompt shortcuts live in .github/prompts/
• Common prompts: ao-plan, ao-task, ao-implement, ao-review, ao-validation, ao-help

Development notes

Isolated workflow/integration tests (mandatory)

Before running integration/UI tests, start the test stack:

docker compose -f docker-compose.test.yml up -d

uv run python scripts/run_isolated_workflow_tests.py

This runs integration tests from an ephemeral temp working directory, not the repo root.

When finished:

docker compose -f docker-compose.test.yml down

One-command local test orchestration (PowerShell)

On Windows/PowerShell, you can prepare dependencies, start the Gitea stack, launch an AO web server, and run both test lanes with:

./scripts/run-all-tests.ps1

Useful switches:

• -DryRun — print the planned commands without executing them
• -KeepDocker — leave the Gitea test stack running after the script finishes
• -KeepWebServer — leave the AO web server running after the script finishes
• -SkipWebServer — run tests without starting the local AO web server helper
• -IncludeBuild — run the canonical build after the explicit test lanes

Build/test commands

uv run python scripts/build.py
uv run pytest tests/ -v

Publishing

• Package name: agent-ops-cli
• CLI name: ao
• Publish workflow: .github/workflows/python-publish.yml
• Local fallback: uv build + uvx twine check dist/* + twine upload

---

Use AO as your workflow source of truth so humans and agents execute from the same issue/event substrate.