@autoclawd/autoclawd 1.0.5 → 1.1.0

package/README.md

@@ -1,88 +1,119 @@
-# autocode
+# autoclawd
 
-Linear tickets in, pull requests out. autocode watches your Linear board, spins up Docker containers, runs [Claude Code](https://docs.anthropic.com/en/docs/claude-code), and opens PRs.
+Linear tickets in, pull requests out. autoclawd watches your Linear board, spins up Docker containers, runs [Claude Code](https://docs.anthropic.com/en/docs/claude-code), and opens PRs — with auto-merge and stacked diffs.
 
 ## How it works
 
 ```
-Linear webhook → autocode → Docker container → Claude Code → git push → PR
+Linear ticket (Todo) → autoclawd → Docker + Claude Code → git push → PR (auto-merge)
 ```
 
-1. A ticket moves to "Todo" in Linear
-2. autocode claims it, clones the repo, creates a branch
+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. autocode pushes the changes and opens a PR
-5. Linear ticket moves to "Done" with a link to the PR
+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
 
-## Quick start
+For dependent tasks, autoclawd handles **stacked diffs** — child PRs branch from parent PRs and auto-rebase when parents merge.
+
+## Install
 
 ```bash
-# Install
-npm install -g autocode
+npm install -g @autoclawd/autoclawd
+```
 
-# Prerequisites: Docker running, Claude Code logged in
-# (run `claude` once to create ~/.claude/.credentials.json)
+Prerequisites: Docker running, Claude Code logged in (`claude` once to create credentials).
 
-# Interactive setup — validates everything
-autocode init
+Docker is auto-started if installed but not running. On macOS, autoclawd opens Docker Desktop automatically.
+
+## Quick start
 
-# Start the webhook server (auto-creates tunnel + Linear webhook)
-autocode serve
+```bash
+# 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 |
 |---------|-------------|
-| `autocode init` | Interactive setup with preflight checks |
-| `autocode serve` | Start webhook server with auto-tunnel |
-| `autocode run T-123` | Run a single ticket |
-| `autocode run T-123 --dry-run` | Preview without executing |
-| `autocode validate` | Check config syntax |
-| `autocode cleanup` | Remove orphaned Docker containers |
+| `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 (`~/.autocode/config.yaml`)
+### Host config (`~/.autoclawd/config.yaml`)
 
-Created by `autocode init`. Contains tokens and global defaults.
+Created by `autoclawd init`. Contains tokens and global defaults.
 
 ```yaml
 linear:
-  apiKey: "lin_api_..."     # or env:LINEAR_API_KEY
+  apiKey: "lin_api_..."        # or env:LINEAR_API_KEY
   teamId: TEAM
-  statuses: [Todo]          # which statuses trigger execution
-  assignToMe: false         # only process tickets assigned to you
+  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
-
-webhook:
-  port: 3000
+  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            # or autocode-base for multi-language
+  image: node:20
   memory: 4g
-  # setup:                  # optional commands to run before Claude
+  # 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
+  # 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 (`.autocode.yaml` or `.autocode.yml`)
+### Per-repo config (`.autoclawd.yaml` or `.autoclawd.yml`)
 
-Optional. Place in the repo root to customize behavior for that repo.
+Optional. Place in the repo root to customize behavior per repo.
 
 ```yaml
 prompt: "You are working on a Django REST API. Follow PEP 8."
-base: develop              # default branch (instead of main)
+base: develop                  # default branch (instead of main)
 
 agent:
   model: claude-opus-4-6
@@ -92,39 +123,79 @@ 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 tell autocode which repository to work on.
+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
 
-When autocode completes a ticket, it automatically adds a `base:autocode/T-123-...` label to the ticket. To stack Ticket B on Ticket A's unmerged PR:
+For dependent tasks where ticket B needs code from ticket A:
 
-1. Ticket A is processed normally (branches from main)
-2. Copy the `base:autocode/A-123-...` label from Ticket A to Ticket B
-3. Ticket B will branch from A's PR branch instead of main
+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
 
-## Docker images
+The rebase happens automatically during the watch poll cycle, or manually via:
+```bash
+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
 
-| Image | Languages | Size | Use when |
-|-------|-----------|------|----------|
-| `node:20` (default) | Node.js | ~300MB | Node/TS repos |
-| `autocode-base` | Node, Python, Go, Rust, Ruby | ~1.5GB | Multi-language repos |
-| Custom | Whatever you need | Varies | Special requirements |
+## Validation hooks
+
+Configure test/lint/build commands that run after Claude Code finishes. Failures are fed back to Claude for fixing.
+
+```yaml
+# 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:
 
-Build the multi-runtime image:
 ```bash
-docker build -t autocode-base .
+autoclawd fix https://github.com/owner/repo/pull/123
 ```
 
-For repos with uncommon dependencies, use `docker.setup` in `.autocode.yaml`:
+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:
+
 ```yaml
 docker:
   setup:
@@ -132,8 +203,6 @@ docker:
     - pip install -r requirements.txt
 ```
 
-autocode also auto-detects common stacks (Python, Go, Ruby) from repo files and installs missing runtimes.
-
 ## Environment variables
 
 Any config value can reference environment variables with the `env:` prefix:
@@ -147,22 +216,30 @@ github:
 
 ## Monitoring
 
-The webhook server exposes health endpoints:
-
+Health endpoint (webhook/serve mode):
 ```bash
 curl http://localhost:3000/health
 # {"status":"ok","active":1,"queued":0,"capacity":2}
 ```
 
-Logs are written to `~/.autocode/logs/autocode-YYYY-MM-DD.log`.
+Logs: `~/.autoclawd/logs/autoclawd-YYYY-MM-DD.log`
+
+Run history:
+```bash
+autoclawd history
+autoclawd history --failed
+autoclawd history --json
+```
 
 ## Security
 
-- Config file is written with `0600` permissions (owner-only read/write)
-- Git credentials use `GIT_ASKPASS` / credential helpers (never in URLs or process list)
-- Webhook signature verification (HMAC-SHA256) when signing secret is configured
+- 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autoclawd/autoclawd",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Linear tickets → Claude Code in Docker → PRs",
   "type": "module",
   "bin": {