Installation

autoducks is runtime-agnostic by design. The agent scripts, provider implementations, and core utilities live in .autoducks/ and are independent of any specific CI/CD platform. The runtime layer — the workflow files that wire triggers to scripts — is a separate concern.

Currently supported runtime: GitHub Actions. Other runtimes are planned.

Prerequisites (GitHub Actions runtime)

A repository hosted on GitHub (personal or org)
gh CLI authenticated (gh auth login)
An Anthropic API key (from console.anthropic.com)
The Claude Code GitHub App installed on your repo

The pipeline runs fully on the default repo + workflow token permissions — no extra scopes required. A token with read:org scope, exposed to the workflow as AUTODUCKS_ORG_TOKEN, is optional and only needed for two @org/team-based features:

CODEOWNERS authz — expanding @org/team entries in .github/CODEOWNERS when security.codeowners is enabled. See Team-expansion token limitation.
Team-based reviewer routing — auto-assigning reviewers to task/feature PRs from a GitHub team.

Without AUTODUCKS_ORG_TOKEN, both of these degrade gracefully: team entries are skipped (or PRs are created without auto-assigned reviewers) and a warning is recorded — the pipeline itself does not fail.

One-line install

Run this from the root of your repository:

curl -fsSL https://raw.githubusercontent.com/deepducks/autoducks/main/scripts/install.sh | bash

This downloads the .autoducks/ directory tree and copies the GitHub Actions workflow files to .github/workflows/.

Install options

# Specify a different repo (if not running inside the target repo)
curl -fsSL .../install.sh | bash -s -- --repo OWNER/REPO

# Download files only, skip the setup checks
curl -fsSL .../install.sh | bash -s -- --no-setup

What gets installed

Path	Description
`.autoducks/`	Agent scripts, prompts, provider implementations, core utilities
`.autoducks/runtimes/github-actions/`	GitHub Actions workflow definitions (one per agent)
`.github/workflows/autoducks-*.yml`	Copies of the runtime workflows, placed where GitHub Actions expects them
`.github/ISSUE_TEMPLATE/`	Issue templates for feature and task issues
`scripts/`	`setup.sh`, `install.sh`, `smoke-test.sh`

The runtime workflows in .github/workflows/ are copies of the canonical definitions in .autoducks/runtimes/github-actions/. The setup script verifies they stay in sync.

Setup checks

After installing, run scripts/setup.sh to validate your repository:

./scripts/setup.sh

The script checks and auto-creates what it can, and reports what requires manual action:

ITS authentication — verifies gh auth status (GitHub CLI). Fatal if missing.
Required labels — creates Feature, Bug, Task, Draft, smoke-test, and the stage labels if they don’t exist.
LLM provider secret — checks that ANTHROPIC_API_KEY is set as a repository secret. If missing, prints the command to add it:
Terminal window
```
gh secret set ANTHROPIC_API_KEY --repo OWNER/REPO
```
Runtime workflow permissions — checks for write permissions and can_approve_pull_request_reviews: true on GitHub Actions. Prints the fix command if wrong.
Claude Code GitHub App — reminds you to install the app at github.com/apps/claude. Cannot be verified programmatically.
Issue types (Feature, Task) — checks org-level issue types. Workflows run without them, but typed issue relationships won’t appear in the issue tracker UI. Routing is driven by labels (which the Architect and Engineer apply automatically); the native type is a visual enhancement for org repos.
Sub-issues API — GitHub’s native sub-issue relationship. Available on every GitHub-hosted repository as of October 2024. The Engineer uses this to link each task to its parent Feature so a progress bar and “Parent issue” backlink render in the GitHub UI. Autoducks probes at runtime and falls back to the markdown ## Progress checklist if the API is unavailable, so no manual setup is required.
Runtime workflow sync — verifies that .github/workflows/autoducks-*.yml match .autoducks/runtimes/github-actions/. Fails if out of sync.

After a successful setup, validate the full pipeline with the smoke test:

./scripts/smoke-test.sh --cleanup

This creates a test feature issue, runs it through the full design → plan → execution loop, and cleans up afterward.

Updating

Re-run the install script to update to the latest version:

curl -fsSL https://raw.githubusercontent.com/deepducks/autoducks/main/scripts/install.sh | bash

It detects the existing .autoducks/autoducks.json and runs in update mode (skips setup).

Configuration

After installing, you can customize defaults in .autoducks/autoducks.json:

{
  "command": "",
  "providers": {
    "its": "github",
    "git": "github",
    "llm": "claude"
  },
  "defaults": {
    "model": "claude-sonnet-5",
    "effort": "high",
    "base_branch": "main"
  }
}

See Configuration reference for all options.