autoclawd

Linear tickets in, pull requests out. autoclawd watches your Linear board, spins up Docker containers, runs Claude Code, and opens PRs — with auto-merge and stacked diffs.

How it works

Linear ticket (Todo) → autoclawd → Docker + Claude Code → git push → PR (auto-merge)

1. A ticket moves to "Todo" in Linear (manually or via Claude app with Linear connector)
2. autoclawd claims it, clones the repo, creates a branch
3. Claude Code works on it inside a Docker container (multiple iterations)
4. Validation hooks run (tests, lint, build) — failures are fed back to Claude for fixing
5. autoclawd pushes, opens a PR, and enables auto-merge
6. Linear ticket moves to "Done" with a link to the PR

For dependent tasks, autoclawd handles stacked diffs — child PRs branch from parent PRs and auto-rebase when parents merge.

Install

npm install -g @autoclawd/autoclawd

Prerequisites: Docker running, Claude Code logged in (claude once to create credentials).

Docker is auto-started if installed but not running. On macOS, autoclawd opens Docker Desktop automatically.

Quick start

# Interactive setup — validates tokens, Docker, Claude credentials
autoclawd init

# Start watching Linear for tickets (runs in background)
autoclawd watch

# Or run a single ticket
autoclawd run RAH-123

Commands

| Command | Description | |---------|-------------| | autoclawd init | Interactive setup with preflight checks | | autoclawd watch | Poll Linear for tickets (background by default) | | autoclawd watch --foreground | Poll in foreground (see logs in terminal) | | autoclawd stop | Stop the background watcher | | autoclawd serve | Start webhook server with tunnel | | autoclawd run T-123 | Run a single ticket | | autoclawd run T-123 --dry-run | Preview without executing | | autoclawd fix <PR-URL> | Fix failed CI checks on a PR | | autoclawd retry T-123 | Retry a failed ticket | | autoclawd retry --all-failed | Retry all unresolved failures | | autoclawd rebase [owner/repo] | Rebase stacked PRs whose base was merged | | autoclawd history | Show run history | | autoclawd cleanup | Remove orphaned Docker containers | | autoclawd validate | Check config syntax |

Configuration

Host config (~/.autoclawd/config.yaml)

Created by autoclawd init. Contains tokens and global defaults.

linear:
  apiKey: "lin_api_..."        # or env:LINEAR_API_KEY
  teamId: TEAM
  statuses: [Todo]             # which statuses trigger execution
  assignToMe: false            # only process tickets assigned to you
  inProgressStatus: In Progress
  doneStatus: Done

github:
  token: "ghp_..."             # or env:GITHUB_TOKEN
  autoMerge: true              # enable auto-merge on PRs (default: false)
  mergeMethod: squash           # merge | squash | rebase (default: squash)

docker:
  image: node:20
  memory: 4g
  # setup:                     # commands to run before Claude Code
  #   - pip install -r requirements.txt
  # volumes:                   # extra bind mounts
  #   - "~/.ssh:/home/autoclawd/.ssh:ro"
  # network: bridge            # bridge | host | none

agent:
  model: claude-sonnet-4-6
  maxIterations: 10
  # timeout: 1800              # per-iteration timeout in seconds

safety:
  # allowedRepos:              # restrict which repos can be targeted
  #   - owner/repo-a
  #   - owner/repo-b
  branchPrefix: "autoclawd/"   # all branches must start with this
  # maxFileChanges: 100        # fail if too many files changed

# validate:                    # global validation commands
#   - npm test
#   - npm run lint

maxConcurrent: 1

Per-repo config (.autoclawd.yaml or .autoclawd.yml)

Optional. Place in the repo root to customize behavior per repo.

prompt: "You are working on a Django REST API. Follow PEP 8."
base: develop                  # default branch (instead of main)

agent:
  model: claude-opus-4-6
  maxIterations: 20

docker:
  image: python:3.12
  setup:
    - pip install -e ".[dev]"

validate:
  - pytest
  - ruff check .

Repo routing

Tickets need a repo:owner/name label in Linear to route to the correct GitHub repo.

Examples:

• repo:acme/backend
• repo:acme/frontend
• repo:https://github.com/acme/monorepo

If the repo doesn't exist, autoclawd creates it automatically and pushes an initial scaffold.

Stacked diffs

For dependent tasks where ticket B needs code from ticket A:

1. Ticket A is processed normally (branches from main)
2. After A completes, autoclawd adds a base:autoclawd/RAH-100-... label to it
3. Ticket B gets that label → it branches from A's PR branch instead of main
4. When A's PR merges, autoclawd auto-rebases B onto main and retargets the PR

The rebase happens automatically during the watch poll cycle, or manually via:

autoclawd rebase owner/repo

Setting up stacked diffs from the Claude app

When using the Claude app with a Linear connector to create tickets, tell Claude:

• "Task B depends on task A" → Claude adds the base:autoclawd/RAH-{A}-... label to B

Validation hooks

Configure test/lint/build commands that run after Claude Code finishes. Failures are fed back to Claude for fixing.

# In .autoclawd.yaml or host config
validate:
  - npm test
  - npm run lint
  - npm run build

• PRs start as draft while validation runs
• If all pass → PR marked ready (+ auto-merge if enabled)
• If still failing after max iterations → PR stays draft with failure details in the body

CI fix mode

Fix failing CI checks on an existing PR without a Linear ticket:

autoclawd fix https://github.com/owner/repo/pull/123

autoclawd fetches the failed check logs, spins up Claude Code on the PR branch, and pushes fixes.

Docker images

| Image | Use when | |-------|----------| | node:20 (default) | Node.js / TypeScript repos | | python:3.12 | Python repos | | ubuntu:24.04 | General purpose | | Any image | autoclawd auto-installs git + Claude Code if missing |

autoclawd auto-detects common stacks (Python, Go, Ruby) from repo files and installs missing runtimes. Use docker.setup for anything custom:

docker:
  setup:
    - apt-get update && apt-get install -y libpq-dev
    - pip install -r requirements.txt

Environment variables

Any config value can reference environment variables with the env: prefix:

linear:
  apiKey: env:LINEAR_API_KEY
github:
  token: env:GITHUB_TOKEN

Monitoring

Health endpoint (webhook/serve mode):

curl http://localhost:3000/health
# {"status":"ok","active":1,"queued":0,"capacity":2}

Logs: ~/.autoclawd/logs/autoclawd-YYYY-MM-DD.log

Run history:

autoclawd history
autoclawd history --failed
autoclawd history --json

Security

• Config file written with 0600 permissions (owner-only)
• Git credentials via GIT_ASKPASS / credential helper (never in URLs or process list)
• Webhook signature verification (HMAC-SHA256) when signing secret configured
• Request body size limit (1 MB)
• Token redaction in error messages
• Branch prefix enforcement prevents writes outside autoclawd/ namespace
• Optional repo allowlist (safety.allowedRepos)

License

MIT