wade-cli 0.35.1

WADE — Workflow for AI-Driven Engineering

WADE — Workflow for AI-Driven Engineering

AI tools write the code. WADE handles everything else.

Every Wade does the dirty work so the heroes don't have to.

Branches, worktrees, context loading, model selection, PR creation — all the workflow friction that surrounds AI coding sessions. WADE eliminates it. Works with Claude Code, Copilot, Antigravity CLI, Codex, and more. Run wade init once per project, then just point it at a GitHub (more to come!) issue number.

See It in Action

Starting work on Issue #42:

Without WADE:

git fetch origin && git checkout main && git pull
git checkout -b feat/issue-42-user-auth
# paste issue title + description into AI chat
# explain your branching rules, test locations, linters to run...

With WADE:

wade 42

WADE fetches the issue, detects whether it's been planned, and starts the right session automatically — planning if no plan exists yet, implementation if it does. Creates an isolated git worktree, launches your AI tool with the full issue loaded — title, description, labels, and all your project conventions — and Skills guide the AI from first commit to open PR without you touching git again.

Finishing work and opening the PR:

Without WADE:

git checkout main && git pull
git checkout feat/issue-42-user-auth
git merge main          # resolve conflicts yourself, if any
git push
gh pr create --title "User Auth (#42)" --body "..."   # write description manually
# don't forget to link the issue, clean up the branch...

With WADE (the AI handles all of this):

wade implementation-session done

The AI merges the latest main into the branch, resolves any conflicts, writes the PR description from what it built, and marks it ready for review — you get a clean, already-integrated diff with no noise for your reviewer.

Working on multiple issues at once:

wade implement-batch 42 43 44   # three worktrees, three AI sessions, zero stashing

Why WADE

Without WADE	With WADE
git fetch && checkout && pull && checkout -b ... before every task	wade 42 — one command, done
Copy-paste issue title + description into AI chat every time	Full issue context + project conventions loaded automatically
One task at a time, or stash-juggle between branches	Parallel issues in isolated worktrees, zero conflicts
Re-explain your branching rules, test commands, linters every session	Skills teach the AI your conventions once
PRs opened on stale branches — reviewer sees conflict noise, asks for a rebase, CI fails	AI merges the latest main and resolves conflicts before the PR — reviewer sees only your changes
Write the PR description, link the issue, clean up the branch — manually	The AI ships the PR. You just review
Manually pick the right model for each task	Automatic model routing based on issue complexity
Which terminal tab has which issue? No idea	Terminal title shows wade implement #42 — Feature Name
Which AI session worked on this issue? Which tool? Which model?	Every PR and issue logs the tool, model, and session resume command — for both Plan and Implement phases

Installation

One-line install script (installs uv automatically if missing):

curl -LsSf https://raw.githubusercontent.com/ivanviragine/wade/main/install.sh | sh

Or, if you already have uv or pipx:

uv tool install wade-cli    # recommended
pipx install wade-cli

Requires gh CLI (authenticated) and at least one supported AI coding tool.

gh auth login    # if not already authenticated

Quick Start

Initialize WADE in your project (once):

wade init

Then start working:

# Plan a feature — AI creates GitHub issues and draft PRs
wade plan

# Start working — WADE detects plan state and picks the right session automatically
wade 42

Commands

Command	Description
wade <N>	Smart shorthand — routes to implement or review pr-comments automatically
wade plan	AI planning session — creates issues + draft PRs
wade implement <N>	Create worktree and start AI session for an issue
wade implement-batch <N> <M> ...	Start parallel sessions for multiple issues (beta)
wade review pr-comments <N>	Address PR review comments
wade review plan <file>	AI-powered plan review
wade review implementation	AI-powered code review
wade review batch <N>	Coherence review across parallel implementation branches
wade cd <N>	Navigate to a worktree (requires shell integration)
wade task create	Create a GitHub issue interactively
wade task list	List open issues
wade task read <N>	Show issue details
wade task deps <N> <M> ...	Analyze dependencies between issues
wade worktree list	List active worktrees
wade worktree remove <N>	Remove a worktree
wade init	Initialize WADE in the current project
wade update	Upgrade WADE and refresh project files
wade deinit	Remove WADE from the current project
wade check-config	Validate .wade.yml configuration
wade knowledge add	Append a project learning from stdin
wade knowledge get	Print the current project knowledge file
wade knowledge rate	Record a thumbs-up or thumbs-down for a knowledge entry
wade knowledge enable [--path PATH]	Enable knowledge capture and optionally set custom file path
wade knowledge disable	Disable knowledge capture (keeps existing knowledge file)

Short aliases: wade p (plan), wade i <N> (implement), wade r <N> (review pr-comments).

Most workflow commands accept --ai <tool>, --model <model>, --effort <level>, --permission-mode <tier>, and --yolo to override configured defaults. implement also supports --detach (new terminal tab) and --cd (print worktree path only).

--permission-mode sets how much autonomy the AI tool is granted — an axis independent of the delegation --mode (which controls how a tool is dispatched: prompt/interactive/headless). The tiers, most→least permissive, are yolo > auto > accept-edits > default:

Tier	Behavior
default	Prompt for every action (no autonomy grant).
accept-edits	Auto-apply file edits; still prompt for shell/commands. Claude and Antigravity CLI.
auto	Classifier-mediated auto mode (a model reviews each non-read action). Claude only.
yolo	Full autonomy — no prompts.

--yolo is a back-compat alias for --permission-mode yolo; an explicit --permission-mode wins when both are given. The same values are accepted in .wade.yml as ai.permission_mode (global) or ai.<command>.permission_mode (per-command), with yolo: true still honored as the alias. A tier a tool doesn't support is downgraded automatically (e.g. auto → accept-edits on non-Claude tools) with a warning — WADE forwards the requested tier and crossby owns the downgrade ladder. Headless commands (deps, review_*) always run at default. plan is not a permission mode — it's driven separately — and is rejected (warn + fall back to default) if configured.

wade plan --issue <N> re-plans an existing issue. If the session produces a single plan file, it's attached to #N and the issue stays open. If the session decides the work should be split into several independent pieces (2+ plan files), #N is superseded: a new issue + draft PR is created per plan file, a comment and a > **Superseded by ...** banner are added to #N, and it's closed as not planned (confirmed via prompt unless --yolo/non-interactive). If any plan file fails to become an issue, #N is left open with a warning instead of superseding on a partial split.

Supported AI Tools

Adapters, model/effort resolution, and per-tool config (allowlists, hooks) are powered by crossby, WADE's AI-tool-integration dependency.

Tool	Binary
Claude Code	claude
Cursor	cursor
GitHub Copilot	copilot
OpenAI Codex	codex
OpenCode	opencode
VS Code	code
Antigravity IDE	antigravity
Antigravity CLI	agy

In .wade.yml, refer to a tool by its config ID, which matches the binary above except for VS Code (vscode) and Antigravity CLI (antigravity-cli). Antigravity IDE (config ID antigravity) is launch-only — WADE opens your workspace in the desktop app; its workflow files are provisioned via the Antigravity CLI's shared .agents/ layout.

Task Providers

WADE can pull tasks from three backends — pick one when you run wade init:

Provider	Where issues live	Auth
github (default)	GitHub Issues	gh CLI
clickup	ClickUp list	API token in env var
markdown	A single committed ISSUES.md	None

PRs always flow through GitHub regardless of choice — wade fetch-reviews, the auto-poll loop, and review-thread resolution work identically across providers.

Markdown provider

Useful when you want issues versioned alongside the code, with no external service. Each issue is one ## heading in the file:

# Wade Issues

## #47239185 Add login feature

<!-- wade
state: open
labels: feature, complexity:medium
-->

Description body here. Sub-headings, code blocks, anything markdown.

• The file is resolved against the main worktree, so every linked worktree reads/writes the same physical file. No textual merge conflicts on ISSUES.md.

• IDs are random 8-digit decimal so two parallel wade implement sessions in different worktrees can't collide. They stay numeric so existing #NN checklist refs in tracking-issue bodies still work.

• Configure via .wade.yml:

  provider:
    name: markdown
    settings:
      path: ISSUES.md      # relative to repo root, or absolute
      auto_commit: false   # if true, close_task auto-commits the change
  

• After a PR merges, provider.close_task flips the section's state to closed in ISSUES.md. By default the file is left modified in your working tree — commit it yourself. Set auto_commit: true to have wade commit the change with a chore: close #N message; failures (not a git repo, hook rejection, signing required) are logged and swallowed so the close itself never blocks.

• Tracking issues with - [ ] #N checklist bodies work the same as with GitHub Issues — markdown's find_parent_issue scans every section's body for child refs.

Agent Skills

wade init installs Skills that teach your AI agent the workflow — issue format, planning rules, implementation session rules, and dependency analysis. Skills, the AGENTS.md workflow pointer, and any tool-specific configuration are set up automatically for every supported tool. Nothing to configure manually.

Skill	Purpose
task	GitHub issue creation and plan format
plan-session	Planning session rules and workflow
implementation-session	Implementation session rules and workflow
review-pr-comments-session	Review session rules and workflow
deps	Dependency analysis between issues

Worktree Hooks

Configure automated setup when worktrees are created via wade implement or wade implement-batch. Add a hooks section to .wade.yml:

hooks:
  post_worktree_create: scripts/setup-worktree.sh
  copy_to_worktree:
    - .env
    - .env.example

post_worktree_create — A setup script to run after each worktree is created. Use it to install dependencies, run builds, or prepare the environment so worktrees are ready to use immediately.

copy_to_worktree — Files to copy from the project root into the worktree before running the hook. Useful for secrets and config files (e.g., .env) that are gitignored and wouldn't otherwise be present in a new worktree.

See templates/setup-worktree.sh.example for a starter script.

Shell Integration

To make wade cd <N> actually change your directory (instead of just printing the path), add this to your shell profile:

eval "$(wade shell-init)"

Tab completion:

wade --install-completion bash   # or zsh / fish

Upgrading

wade update

Detects your install method (uv tool, pipx, Homebrew) and upgrades automatically, then refreshes all managed project files.

Contributing

See CONTRIBUTING.md.

License

MIT