# Setup guide — AI Bug-Fix & Draft-PR Agent

## 1. Install and create a sandbox runner

Install the agent and prepare an isolated workspace it can clone into.

```
pipx install bugfix-agent
mkdir -p ~/.bugfix-sandbox
bugfix-agent doctor   # checks git, test runner, sandbox isolation
```

## 2. Configure models, repo access, and limits

Use a least-privilege token. Caps live in config so the agent cannot widen its own scope.

```
cp .env.example .env
ANTHROPIC_API_KEY=sk-ant-...
GITHUB_TOKEN=ghp_...            # scoped: contents:write, pull_requests:write on ONE repo
TEST_CMD="pytest -q"
MAX_FILES=8
MAX_DIFF_LINES=200
REQUIRE_TEST=true
```

## 3. Declare protected paths

Anything matching these is off-limits to the agent and forces escalation.

```
# .bugfix.yml
protected_paths:
  - "**/auth/**"
  - "**/payments/**"
  - "migrations/**"
  - "infra/**"
open_as: draft
base_branch: main
```

## 4. Dry-run on a real issue

Point it at an issue and inspect the plan, patch, and test before letting it open a PR.

```
bugfix-agent run --issue 1423 --dry-run --explain
# prints decision, root_cause, patch, test, risks
```

## 5. Enable PR creation in CI

Trigger on labeled issues so a human stays in the loop by choosing what to hand the agent.

```
# .github/workflows/bugfix.yml
name: Autonomous Bug Fix
on:
  issues:
    types: [labeled]
jobs:
  fix:
    if: github.event.label.name == 'agent-fix'
    runs-on: ubuntu-latest
    permissions: { contents: write, pull-requests: write }
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: pipx install bugfix-agent
      - run: bugfix-agent run --issue ${{ github.event.issue.number }} --open-pr
        env: { ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}, GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} }
```
