Local-first PR review autopilot for Cursor Bugbot - watches GitHub PR comments, applies fixes via Cursor CLI, and commits in cycles
npm install @tenxtools/bugfixbotLocal-first PR review autopilot for Cursor Bugbot. Watches GitHub PR comments for Bugbot findings, applies fixes via Cursor CLI, runs verification checks, and commits in cycles until no actionable comments remain.
``bash`
npm install -g @tenxtools/bugfixbot
`bashInitialize in your project
bugfixbot init
How It Works
`
┌─────────────────────────────────────────────────────────────┐
│ Fix Loop Cycle │
├─────────────────────────────────────────────────────────────┤
│ 1. Fetch Bugbot comments from GitHub PR │
│ 2. Filter to actionable, unhandled comments │
│ 3. Build fix prompt with file locations + context │
│ 4. Apply fixes via Cursor CLI │
│ 5. Run verification (tests, lint, typecheck) │
│ 6. Commit and push: "chore(bugbot): fix review findings" │
│ 7. Repeat until 0 actionable comments or max cycles │
└─────────────────────────────────────────────────────────────┘
`Configuration
Create
bugfixbot.yml in your project root (or run bugfixbot init):`yaml
github:
# repo: owner/repo # Optional: inferred from git remote
# pr: 123 # Optional: inferred from branch
auth: env # 'gh' (use gh CLI), 'token', or 'env' (GITHUB_TOKEN)
botAuthors:
- cursor-bot
- bugbotfix:
engine: cursor-cli # 'cursor-cli' or 'cursor-command'
# command: bugbot_fix # For cursor-command engine
verification:
commands:
- npm run typecheck
- npm run lint
- npm test
timeout: 300000 # 5 minutes per command
stopOnFailure: true
guardrails:
maxCycles: 5
maxFilesPerCycle: 10
maxLinesPerCycle: 500
pollIntervalMs: 30000
git:
commitTemplate: "chore(bugbot): fix review findings [cycle {cycle}]"
autoRebase: false
pushForce: false
`CLI Commands
$3
Initialize bugfixbot in the current directory. Creates:
-
bugfixbot.yml - Configuration file
- .cursor/commands/bugbot_fix.md - Cursor command template
- .bugfixbot/ - State directory (gitignored)`bash
bugfixbot init [--force] [--skip-templates]
`$3
Run a single fix cycle.
`bash
bugfixbot run --pr [--repo owner/repo] [--config path]
`$3
Watch mode: continuously run fix cycles until done or max cycles reached.
`bash
bugfixbot watch --pr [--max-cycles 5] [--poll-interval 30000]
`$3
Show current status, pending comments, and session state.
`bash
bugfixbot status --pr
`GitHub Authentication
bugfixbot supports three authentication methods:
1.
gh CLI (recommended): Uses gh auth token to get credentials
2. Environment variable: Set GITHUB_TOKEN or GH_TOKEN
3. Explicit token: Set github.token in configGuardrails
Built-in safety guardrails prevent runaway automation:
| Setting | Default | Description |
|---------|---------|-------------|
|
maxCycles | 5 | Stop after N cycles |
| maxFilesPerCycle | 10 | Require approval if exceeded |
| maxLinesPerCycle | 500 | Require approval if exceeded |
| pollIntervalMs | 30000 | Wait between cycles |
| stopOnTestFailure | true | Halt if verification fails |Customizing Fix Prompts
For teams wanting custom fix behavior, use the
cursor-command engine with templates in .cursor/commands/:`yaml
fix:
engine: cursor-command
command: bugbot_fix # Uses .cursor/commands/bugbot_fix.md
`Templates support placeholders:
-
{{prompt}} - The generated fix prompt
- {{taskCount}} - Number of tasks
- {{files}} - Comma-separated file listProgrammatic Usage
`typescript
import { runLoop, loadConfig, createGitHubClient } from '@tenxtools/bugfixbot';const config = loadConfig({ cwd: process.cwd() });
const octokit = createGitHubClient({ auth: config.github.auth });
const result = await runLoop({
octokit,
config,
owner: 'your-org',
repo: 'your-repo',
prNumber: 123,
cwd: process.cwd(),
});
console.log(result.status); // 'complete' | 'pushed' | 'stopped' | 'failed'
`Requirements
- Node.js >= 18
- Cursor CLI installed and authenticated
- GitHub access (via
gh` CLI or token)Apache-2.0