@tenxtools/bugfixbot

Local-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.

Installation

npm install -g @tenxtools/bugfixbot

Quick Start

# Initialize in your project
bugfixbot init

# Run a single fix cycle
bugfixbot run --pr 123

# Watch mode: continuously fix until done
bugfixbot watch --pr 123

# Check status
bugfixbot status --pr 123

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):

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
    - bugbot

fix:
  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

bugfixbot init

Initialize bugfixbot in the current directory. Creates:

• bugfixbot.yml - Configuration file
• .cursor/commands/bugbot_fix.md - Cursor command template
• .bugfixbot/ - State directory (gitignored)

bugfixbot init [--force] [--skip-templates]

bugfixbot run

Run a single fix cycle.

bugfixbot run --pr <number> [--repo owner/repo] [--config path]

bugfixbot watch

Watch mode: continuously run fix cycles until done or max cycles reached.

bugfixbot watch --pr <number> [--max-cycles 5] [--poll-interval 30000]

bugfixbot status

Show current status, pending comments, and session state.

bugfixbot status --pr <number>

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 config

Guardrails

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/:

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 list

Programmatic Usage

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)

License

Apache-2.0