Sentinel Code Review Bot - Architecture and Configuration

sentinel-architecture.md

Sentinel Code Review Bot - Architecture

Sentinel is an automated code review bot that reviews PRs across marc-campbell repositories using OpenClaw as its brain.

Components

1. sentinel-bot VPS (Hetzner)

• Runs OpenClaw with Claude Sonnet 4.5
• Tailscale hostname: sentinel-bot
• Workspace: /root/clawd/

2. Webhook Handler (/usr/local/bin/sentinel-webhook.js)

• Node.js HTTP server on port 8888
• Receives PR events from GitHub Actions
• Creates GitHub Check Run via GitHub App
• Triggers OpenClaw agent with PR details

3. GitHub App ("SentinelBot Code Review")

• App ID: 2769267
• Installation ID: 107212994
• Private key stored at: /root/clawd/.github-app.pem
• Used to create/update Check Runs (shows spinner → pass/fail)

4. GitHub Account (@TheBotSentinel)

• PAT stored at: /root/clawd/.secrets as SENTINEL_GITHUB_TOKEN
• Used to post PR reviews and approvals
• Separate account needed because you can't approve your own PRs

5. Tailscale Funnel

• Exposes webhook at: https://sentinel-bot.tail311b.ts.net/webhook
• Proxies to http://127.0.0.1:8888

Flow

1. PR opened/updated
      ↓
2. GitHub Action runs (.github/workflows/sentinel.yml)
      ↓
3. Action POSTs to https://sentinel-bot.tail311b.ts.net/webhook
   (includes repo, PR number, title, head_sha)
      ↓
4. Webhook creates Check Run via GitHub App (shows yellow spinner)
      ↓
5. Webhook triggers: openclaw agent --message "Review PR #X..."
   (includes CHECK_RUN_ID in message)
      ↓
6. Sentinel (OpenClaw) reviews the PR:
   - Fetches PR diff via `gh`
   - Loads Carbon rules (coding standards)
   - Analyzes changes
   - Posts inline comments for issues
   - Posts review (approve/request-changes) as @TheBotSentinel
      ↓
7. Sentinel updates Check Run via GitHub App (green ✓ or red ✗)

Configuration Files

AGENTS.md (Sentinel's instructions)

Location: /root/clawd/AGENTS.md

Defines:

• Review workflow steps
• How to fetch PR details
• Carbon rules integration
• Review format (concise: "🛡️ N files — X issues")
• Check Run update commands

.secrets (credentials)

Location: /root/clawd/.secrets

SENTINEL_GITHUB_TOKEN=ghp_xxx  # @TheBotSentinel PAT for reviews

.github-app.pem (GitHub App private key)

Location: /root/clawd/.github-app.pem

Webhook script

Location: /usr/local/bin/sentinel-webhook.js

• Creates JWT from App private key
• Gets installation token
• Creates Check Run with in_progress status
• Passes CHECK_RUN_ID to OpenClaw agent

Check Run updater

Location: /usr/local/bin/update-check-run.js Usage: node update-check-run.js <owner> <repo> <check_run_id> <conclusion> [summary]

• conclusion: success | failure

Per-Repo Setup

To add Sentinel to a new repo:

1. Copy the workflow file:

# .github/workflows/sentinel.yml
name: Code Review Router
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

jobs:
  dispatch:
    name: Determine code review agents
    runs-on: ubuntu-latest
    if: github.event.pull_request.draft == false
    steps:
      - name: Trigger Sentinel
        env:
          PR_TITLE: ${{ github.event.pull_request.title }}
        run: |
          curl -sSf -X POST "https://sentinel-bot.tail311b.ts.net/webhook" \
            -H "Content-Type: application/json" \
            -H "X-GitHub-Event: pull_request" \
            -d "$(jq -n \
              --arg action "${{ github.event.action }}" \
              --arg repo "${{ github.repository }}" \
              --arg title "$PR_TITLE" \
              --arg head_sha "${{ github.event.pull_request.head.sha }}" \
              --argjson number "${{ github.event.pull_request.number }}" \
              '{
                action: $action,
                repository: {full_name: $repo},
                pull_request: {
                  number: $number,
                  title: $title,
                  head: {sha: $head_sha}
                }
              }')"

2. Install the GitHub App on the repo (for Check Runs)

3. Add repo to Sentinel's monitoring list in AGENTS.md

Editing Sentinel

Sentinel's behavior is controlled by its AGENTS.md file. To modify:

# SSH to sentinel-bot
ssh root@sentinel-bot

# Edit the instructions
nano /root/clawd/AGENTS.md

# Changes take effect immediately (next review)

Or from Rooty:

# Edit locally
nano /tmp/sentinel-agents.md

# Copy to sentinel-bot
scp /tmp/sentinel-agents.md root@sentinel-bot:/root/clawd/AGENTS.md

Troubleshooting

Check webhook logs

ssh root@sentinel-bot "cat /var/log/sentinel-webhook.log"

Restart webhook

ssh root@sentinel-bot "pkill -f sentinel-webhook; nohup node /usr/local/bin/sentinel-webhook.js > /var/log/sentinel-webhook.log 2>&1 &"

Test Check Run update

ssh root@sentinel-bot "node /usr/local/bin/update-check-run.js marc-campbell flibbertigibbeting <check_run_id> success 'Test'"

Verify GitHub App auth

ssh root@sentinel-bot "ls -la /root/clawd/.github-app.pem"

Manager

Sentinel reports to Rooty (root-bot), who coordinates the bot fleet via GitHub Issues in marccampbell/bot-tasks.