killshot

Autonomous issue-fixing CLI. Picks up labeled GitHub issues, fixes them with Claude Code in isolated worktrees, and creates PRs — all unattended.

Install

npm install -g killshot
# or
npx killshot

Prerequisites

• Claude Code CLI (claude command)
• GitHub CLI (gh command, authenticated)
• Git

Quick Start

cd your-repo
killshot init          # Interactive config wizard → .killshot.json
killshot run --dry-run # Preview what would be fixed
killshot run --once    # Fix one issue, then exit
killshot run           # Continuous loop

Commands

| Command | Description | |---------|-------------| | killshot run | Start the continuous issue-fixing loop | | killshot run --once | Fix one issue, then exit | | killshot run --dry-run | Show next issue without acting | | killshot init | Interactive config wizard | | killshot clean | Remove state file + prune stale worktrees |

Global Flags

• --config <path> — Path to config file (default: .killshot.json)
• --verbose — Enable debug logging
• --prompt <path> — Custom prompt template

Config: .killshot.json

{
  "baseBranch": "main",           // Auto-detected: dev > main > master
  "issueLabel": "AI-Fixable",
  "qaCommand": null,              // e.g. "bun run qa" — null skips QA steps
  "worktreeDir": "../killshot-worktrees",
  "worktreeSetup": null,          // Post-worktree script, e.g. "./scripts/setup.sh"
  "failureLabel": "needs-human",
  "maxRetries": 3,
  "cooldown": 10,                 // Seconds between iterations
  "agentName": "killshot",
  "prompt": null                  // null = bundled default template
}

How It Works

1. Finds the oldest open issue with the configured label
2. Filters out issues that already have PRs, agent comments, or human assignees
3. Claims the issue with a comment
4. Creates an isolated git worktree
5. Spawns Claude Code with a structured prompt to fix the issue
6. On success: PR is created, worktree cleaned up, moves to next issue
7. On failure: retries up to maxRetries, then labels the issue for human review

Graceful Shutdown

Ctrl+C during a run preserves state. Next killshot run resumes where it left off.

Custom Prompts

Create a custom prompt template with {{variable}} placeholders:

| Variable | Description | |----------|-------------| | {{repoRoot}} | Repository root path | | {{worktreePath}} | Current worktree path | | {{agentName}} | Agent name from config | | {{baseBranch}} | Base branch for PRs | | {{qaCommand}} | QA command (empty if null) | | {{issueLabel}} | Issue label to pick up | | {{failureLabel}} | Label for failed issues | | {{maxRetries}} | Max retry count | | {{issueNumber}} | Current issue number | | {{issueTitle}} | Current issue title | | {{issueBody}} | Current issue body |

Conditional blocks: {{#qaCommand}}...{{/qaCommand}} — removed entirely if qaCommand is null.

License

MIT