Tao

Local-first AI coding workflow orchestration for planning, verified slices, isolated Git worktrees, exact-diff review, recovery, and safe merges.

Tao augments supported coding agents with a durable local workflow for turning a request into small, reviewable changes:

1. Plan the outcome with /tao-plan.
2. Slice the plan into bounded steps with /tao-slice.
3. Validate its artifacts and checks with tao validate.
4. Run each slice in an isolated Git worktree with tao run.
5. Review the exact plan diff; inspect or refresh the result with tao review.
6. Merge or hand off a PR with tao merge or the pull-request run path.

Tao keeps plans, execution evidence, and recovery state locally. It validates agent-proposed commits, verifies completed work, and binds review to an exact base and head before integration. On the PR path, completed means handoff, not integration; only current plan_merged evidence proves default-branch integration.

For workflow guidance, see the usage guide. For the artifact and lifecycle contract, see the plan format.

Where Tao fits

Category	Primary role	Tao's relationship
Coding agents	Generate and change code	Tao augments supported agents with planning, execution, evidence, and integration controls.
Spec-only frameworks	Structure requirements or plans	Tao carries a sliced plan through verified implementation, review, and integration.
Worktree session managers	Isolate or organize coding sessions	Tao creates managed execution worktrees as part of a durable plan lifecycle.
Autonomous PR agents	Independently produce pull requests	Tao orchestrates user-invoked local runs and can hand off a reviewed head to a PR workflow.

Important

Tao is not a replacement for your coding agent, a generic parallel-agent dashboard, or a cloud platform. Today it supports Pi and Claude.

---

Quickstart

Prerequisites

• macOS or Linux on AMD64 or ARM64. Windows is not currently supported.
• Git and either Pi or Claude Code, installed and authenticated. Pi is the default; set TAO_AGENT=claude to select Claude.
• On Linux, bubblewrap (bwrap) is required for the OS-confined resolver and reviewer sessions used by automatic squash-conflict resolution. tao doctor reports whether Tao can find it at a supported system path.
• Go 1.26.2 and make only if you install from source.

Install Tao

Release binary (macOS or Linux): Download the archive for your OS and architecture, plus checksums.txt, from GitHub Releases. Verify the archive before extracting it, then move tao to a directory on your PATH:

shasum -a 256 -c checksums.txt --ignore-missing  # macOS
# sha256sum -c checksums.txt --ignore-missing    # Linux

tar -xzf tao_<version>_<os>_<arch>.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 0755 tao "$HOME/.local/bin/tao"

Ensure $HOME/.local/bin is on PATH. Beta and stable releases both publish checksum-verifiable GitHub assets. Beta releases are GitHub prereleases and do not enter the stable Homebrew or tao update channels.

Homebrew (stable channel): When a stable release is available, install its cask with:

brew install --cask iamseth/tap/tao

From source:

git clone https://github.com/iamseth/tao.git
cd tao
make build
export PATH="$(pwd)/bin:$PATH"

Install Tao's managed prompts, then inspect agent discovery and setup issues:

tao install-prompts
tao doctor

tao doctor provides diagnostic guidance rather than a guaranteed success check. Follow any actionable setup guidance.

Build prompts (/tao-note, /tao-slice, /tao-run, /tao-fix-plan, /tao-commit, /tao-pr) write artifacts, code, or Git state; planning prompts are read-only. See the usage guide for the workflow split.

Complete a first plan

Change to the Git repository you want Tao to manage and register it:

cd /absolute/path/to/your/repository
tao init

Start Pi or Claude in that repository, then enter:

/tao-plan add a --hello flag to the CLI
/tao-slice

/tao-slice prints the new plan ID. Back in your shell, substitute that exact ID and run the plan:

PLAN_ID=20260827-175616-add-hello-flag # replace with the printed plan ID
tao validate "$PLAN_ID"
tao run "$PLAN_ID"
tao review "$PLAN_ID"

If tao run reports that a slice needs approval, inspect the request, approve that slice, and rerun the plan:

SLICE_ID=001-add-hello-flag # replace with the requested slice ID
tao approve --slice "$SLICE_ID" --by you "$PLAN_ID"
tao run "$PLAN_ID"

For a solo local workflow, integrate an approved exact-base/head review with:

tao merge "$PLAN_ID"

Tao creates isolated execution worktrees, runs repository verification, and keeps plans, reviews, execution evidence, and recovery state under its local data home. That data and workspace-local .tao/ metadata are local-only; do not commit them. Tao changes source and Git history only through the workflow steps you invoke.

For workflow choices, interruption recovery, and rework guidance, see the usage guide. For artifact and lifecycle details, see the plan format.

Returning to a repository? Use /tao-catch-me-up in Pi or Claude for a read-only, plain-language highlights list of the last two weeks of local history reachable from HEAD, grouped by features and fixes with commit references. See the usage guide for period and focus examples.

---

Command reference

tao help is the canonical command index, and tao <command> --help shows the current flags, examples, aliases, and recovery guidance for that command. Public commands also accept the short unambiguous prefixes shown by help.

Command group	Commands	Use
Plan	list, show, report, note, validate, staleness, edit, abandon, delete	Capture backlog items and inspect, validate, share, or maintain local plans.
Planner routing	tao route show <route-id>, tao route list, tao route link <route-id> <plan-id>	Inspect the local routing ledger or repair a same-repository plan link; all accept --repo REPO and --json.
Execution	run, commit, approve, review, rework	Execute slices, satisfy gates, inspect exact-diff reviews, and address findings.
Workspace and cleanup	workspace, cleanup, merge	Inspect managed worktrees, clean eligible Git state, and integrate approved plans.
Repository	init, repo, steal	Register checkouts, inspect repository configuration and health, and fetch a read-only scouting snapshot.
Monitoring	ui, monitor, status, insights, log	See cross-repository work, resolved settings, telemetry, and run logs; insights offers --digest or --scorecard, optionally with --all-repos.
Prompts and agents	prompt, draft-prompt, install-prompts	Render, save, and install Tao's agent prompts.
Settings	config, completion, doctor, update	Manage scoped preferences, configure shell support, diagnose setup, and update release binaries.
Other	version, slice-complete, slice-blocked	Inspect the build or support Tao-managed agent lifecycle handoffs and compatibility.

Everyday command paths

Open the terminal dashboard for Notes, Plans (including history), Settings, and Debug. It opens on Plans and supports common actions across registered repositories. Press c on Plans to open plan-detail Changes, a read-only view of the live review-base delta. Press x to open a stuck plan in a foreground fix agent. Use tao status for diagnostics and tao config for saved global/repository preferences:

tao ui
tao monitor --once # non-interactive snapshot

A typical execution path uses tao run <plan>, tao review <plan>, and then tao merge <plan>. If a review requests changes, tao rework <plan> creates bounded follow-up slices; tao rework --run <plan> immediately hands them back to the ordinary run path. Use tao show <plan> whenever you need Tao's recommended next action.

Select a plan reviewer independently with tao run --review-agent claude <plan>, tao review --run --review-agent pi <plan>, or tao rework --run --review-agent claude <plan>. The default inherits TAO_AGENT; TAO_REVIEW_AGENT and tao repo config --review-agent pi|claude|unset supply inherited defaults. Review models are configured separately; rejection never falls back to another runtime. Merge sessions are unchanged. See review runtime configuration.

For an approved set of independent plans, preview batch integration before running it:

tao merge --all --dry-run
tao merge --all
tao merge --all --auto-eject
tao log --batch --follow # follow active batch transitions from another terminal
tao log --prompts <plan> # list captured prompts for a plan

Batch merge keeps the default branch unchanged until the combined result passes full verification and aggregate review. Non-interactive session prompts are captured locally on a best-effort basis; they may contain repository text and must stay local.

tao report --output PATH <plan> writes a share-safe Markdown projection for coworkers with repository access; review it before sharing. See the plan report format for its safety contract.

The usage guide covers workflow judgment and the detailed run/retry, review/rework, pull-request, standalone-commit, and merge recovery paths. Use command help for exact flags and for operational details such as update checks:

tao run --help
tao merge --help
tao update --help

For plan artifact and lifecycle semantics, see the plan format.

Configuration

TAO_AGENT=pi                     # default; or claude
TAO_DATA_HOME=/path/to/tao-data   # optional local data location
TAO_MODEL=provider/model         # optional shared base model
TAO_MAX_REWORK_ATTEMPTS=5         # automatic rework; 0 disables

Precedence is built-in → global → repository → environment → flags, including explicit false values. Save durable preferences with tao config:

tao config set models.model provider/model --global
tao config set pull_request true # current registered repository
tao config unset pull_request    # restore inheritance
tao status                      # effective values, sources, and saved values

Environment now overrides repository defaults; tao repo config remains a compatibility adapter for one release. See the configuration reference for scopes, migration, all settings, budgets, model selection, and planner routing.

See wrap-up and continuation for advisory session warnings and private resume notes.

---

Development

See the contributing guide for repository conventions and local development guidance. Run the canonical make verify gate before opening a pull request. Agent contributors should also follow AGENTS.md.

The repo-local Pi extension hosts /tao-commit, /tao-compose-reply, and the Ctrl+G reply composer. Its extension guide covers behavior, compatibility, testing, and deployment.

Releasing (maintainers)

GitHub Actions and GoReleaser publish checksum-verifiable beta and stable releases. Follow the maintainer releasing guide for the authoritative preparation, tagging, verification, channel, and failure procedures.