claude-beacon 1.0.0 → 1.1.2

package/README.md

@@ -150,6 +150,7 @@ Create or edit `~/.mcp.json` (all projects) or `.mcp.json` in your project root.
   "mcpServers": {
     "claude-beacon": {
       "command": "/home/you/.bun/bin/claude-beacon",
+      "args": ["--author", "YourGitHubUsername"],
       "env": {
         "GITHUB_WEBHOOK_SECRET": "your-secret-from-step-2",
         "GITHUB_TOKEN": "your-pat"
@@ -161,6 +162,8 @@ Create or edit `~/.mcp.json` (all projects) or `.mcp.json` in your project root.
 
 Replace `/home/you` with your home directory (`echo $HOME`). Bun installs globals to `~/.bun/bin/`.
 
+`--author` can be repeated for multiple entries and accepts both GitHub usernames and email addresses (see [`allowed_authors`](#webhook-filters)). It is equivalent to setting `webhooks.allowed_authors` in a config file — use whichever is more convenient.
+
 **If you cloned the repo** (or prefer `bunx` for always-latest):
 
 ```json
@@ -168,7 +171,7 @@ Replace `/home/you` with your home directory (`echo $HOME`). Bun installs global
   "mcpServers": {
     "claude-beacon": {
       "command": "/home/you/.bun/bin/bunx",
-      "args": ["claude-beacon"],
+      "args": ["claude-beacon", "--author", "YourGitHubUsername"],
       "env": {
         "GITHUB_WEBHOOK_SECRET": "your-secret-from-step-2",
         "GITHUB_TOKEN": "your-pat"
@@ -373,9 +376,28 @@ Environment variables (`WEBHOOK_PORT`, `GITHUB_WEBHOOK_SECRET`, `GITHUB_TOKEN`)
 
 | Key | Type | Default | Description |
 |---|---|---|---|
+| `webhooks.allowed_authors` | string[] | **required** | GitHub usernames and/or emails whose PRs trigger actions. See below. |
 | `webhooks.allowed_events` | string[] | `[]` (all) | Allowlist of GitHub event types to process. Empty = accept all supported types |
 | `webhooks.allowed_repos` | string[] | `[]` (all) | Allowlist of repos as `"owner/repo"`. Empty = accept all |
 
+**`allowed_authors` — required field**
+
+claude-beacon will refuse to start if this list is empty. It prevents the agent from rebasing or reviewing your colleagues' PRs.
+
+Two kinds of entries:
+
+- **Username** (no `@`) — matched against `pr.user.login`, the PR author's GitHub handle.
+- **Email** (contains `@`) — matched against `Co-Authored-By` commit trailers. Use this when an AI agent like Devin creates the PR on your behalf: your email appears in the commit even though the bot is the PR author. The co-author lookup makes an extra API call per PR and requires `GITHUB_TOKEN`.
+
+```yaml
+webhooks:
+  allowed_authors:
+    - Matovidlo              # your GitHub username
+    - martin@company.com     # your email, for Devin / AI-agent co-authored PRs
+```
+
+> **Review events** (PR review comments, inline comments) are filtered by username only — no co-author API call — to keep latency low. If a bot creates the PR, add the bot's GitHub login (e.g. `devin-ai-integration[bot]`) as an additional username entry to cover review events for those PRs.
+
 Supported event type strings: `push`, `workflow_run`, `workflow_job`, `check_suite`, `pull_request`, `pull_request_review`, `pull_request_review_comment`, `pull_request_review_thread`, `issue_comment`.
 
 ### Behavior — agent instructions
@@ -386,9 +408,18 @@ These control what Claude is asked to do when an event fires. Each field accepts
 |---|---|---|
 | `behavior.on_ci_failure_main.instruction` | `workflow_run` failure on a main branch | — |
 | `behavior.on_ci_failure_branch.instruction` | `workflow_run` failure on any other branch | — |
-| `behavior.on_pr_review.instruction` | PR review / comment events (after debounce) | `require_plan`, `skill` |
+| `behavior.on_pr_review.instruction` | PR review / comment events (after debounce) | `require_plan`, `skill`, `use_worktree` |
 | `behavior.on_merge_conflict.instruction` | PR with `mergeable_state: dirty` | — |
 | `behavior.on_branch_behind.instruction` | PR with `mergeable_state: behind` | — |
+| `behavior.code_style` | any PR review event | — |
+
+`code_style` is a free-form string prepended to every PR review notification. Describe your project's coding conventions here so Claude applies them consistently when addressing comments.
+
+**`behavior.worktrees`** — controls how subagents handle rebase and PR review work:
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `behavior.worktrees.mode` | `"temp"` \| `"native"` | `"temp"` | `temp`: classic `git worktree add/remove` shell commands. `native`: Claude Code's Agent tool `isolation="worktree"` — Claude manages worktree lifecycle automatically. Use `native` if you work in Claude Code native worktrees. |
 
 **`on_pr_review` sub-fields:**
 
@@ -396,29 +427,41 @@ These control what Claude is asked to do when an event fires. Each field accepts
 |---|---|---|---|
 | `behavior.on_pr_review.require_plan` | boolean | `true` | Whether Claude must enter plan mode before touching code |
 | `behavior.on_pr_review.skill` | string | `"pr-comment-response"` | Skill name invoked to handle the review |
+| `behavior.on_pr_review.use_worktree` | boolean | `false` | When `true`, the PR review subagent runs inside a native Claude Code worktree (`isolation="worktree"`) instead of the current session directory |
 
-**Code style context:**
+### Template placeholders
 
-```yaml
-behavior:
-  code_style: |
-    - Use TypeScript strict mode; never cast to `any`
-    - Prefer `const` over `let`; avoid mutation
-```
+The following placeholders are replaced at runtime inside `instruction` strings. Which placeholders are available depends on the hook:
 
-The `code_style` string is prepended to every PR review notification so Claude applies consistent standards when addressing comments.
+**CI failure hooks** (`on_ci_failure_main`, `on_ci_failure_branch`):
 
-### Template placeholders
+| Placeholder | Value |
+|---|---|
+| `{repo}` | `owner/repo` |
+| `{branch}` | Branch the workflow ran on |
+| `{run_url}` | Full URL of the GitHub Actions run |
+| `{workflow}` | Workflow name |
+| `{status}` | Conclusion (`failure`) |
+| `{commit}` | First line of the head commit message |
 
-The following placeholders are replaced at runtime inside any `instruction` string:
+**PR state hooks** (`on_merge_conflict`, `on_branch_behind`):
 
 | Placeholder | Value |
 |---|---|
 | `{repo}` | `owner/repo` |
-| `{branch}` | Branch name |
 | `{pr_number}` | Pull request number |
-| `{workflow_name}` | Workflow / check name |
-| `{run_id}` | GitHub Actions run ID |
+| `{pr_title}` | PR title (sanitized) |
+| `{pr_url}` | PR URL |
+| `{head_branch}` | PR head branch |
+| `{base_branch}` | PR base branch |
+| `{worktree_steps}` | Auto-generated rebase steps based on `behavior.worktrees.mode` |
+
+**PR review hook** (`on_pr_review`):
+
+| Placeholder | Value |
+|---|---|
+| `{skill}` | Value of `behavior.on_pr_review.skill` |
+| `{worktree_preamble}` | Empty when `use_worktree: false`; a context sentence when `true` |
 
 ### Minimal example
 
@@ -428,13 +471,15 @@ server:
   main_branches: [main, release]
 
 webhooks:
+  allowed_authors:
+    - YourGitHubUsername
   allowed_repos:
     - my-org/my-repo   # only watch this repo
 
 behavior:
   code_style: |
-    - Go 1.23+; run gofmt before committing
-    - All exported symbols must have godoc comments
+    - Use TypeScript strict mode; never cast to `any`
+    - Run linter before committing
   on_pr_review:
     require_plan: true
     skill: pr-comment-response
@@ -534,7 +579,7 @@ Cloudflared free tier gives a new random URL on each restart. Update it: Repo
 ## Development
 
 ```bash
-bun test              # 32 tests
+bun test              # run the test suite
 bun run typecheck     # tsc --noEmit (strict + noUncheckedIndexedAccess)
 bun run lint          # Biome v2
 bun run lint:fix      # Auto-fix lint issues
@@ -555,4 +600,4 @@ Biome v2 is configured in `biome.json` with strict rules. One deliberate deviati
 - `.env` is gitignored — secrets stay local
 - `GITHUB_WEBHOOK_SECRET` is **required** — omitting it causes all requests to be rejected; set `WEBHOOK_DEV_MODE=true` to bypass verification in local dev only
 
-See [AGENTS.md](AGENTS.md) for the full security analysis and architecture reference.
+See [AGENTS.md](AGENTS.md) for the architecture reference and contributor guide.

package/config.example.yaml

@@ -33,6 +33,23 @@ server:
 
 # ── Webhook filters ───────────────────────────────────────────────────────────
 webhooks:
+  # REQUIRED — claude-beacon will not start without at least one entry.
+  #
+  # Controls whose PRs trigger automatic actions (rebase, review response, etc.).
+  # Two kinds of entries:
+  #
+  #   username  (no "@") — matched against the PR author's GitHub login.
+  #   email     (with "@") — matched against Co-Authored-By commit headers.
+  #             Use this when a bot (e.g. Devin) authors the PR on your behalf;
+  #             your email appears in the commit trailer even though the bot is
+  #             listed as the PR author.
+  #
+  # Claude will only act on PRs where the author login OR a commit co-author
+  # email matches an entry in this list.
+  allowed_authors:
+    - YourGitHubUsername
+    # - you@company.com  # uncomment if you use Devin or a similar AI coding agent
+
   # Allowlist of GitHub event types to process.
   # Empty list (default) means all supported events are processed.
   # Useful for narrowing a shared webhook to only the events you care about.
@@ -60,6 +77,23 @@ webhooks:
 # by using names that don't appear in the variable list for that event.
 behavior:
 
+  # ── Worktree mode ────────────────────────────────────────────────────────────
+  # Controls how subagents handle rebase / conflict resolution and PR review work.
+  #
+  #   mode: temp    (default)
+  #     Subagents use classic shell commands:
+  #       git worktree add /tmp/pr-<N>-rebase <branch>
+  #       ... do work ...
+  #       git worktree remove /tmp/pr-<N>-rebase
+  #
+  #   mode: native
+  #     Subagents are spawned via Claude Code's Agent tool with isolation="worktree".
+  #     Claude manages the worktree lifecycle automatically — no add/remove commands.
+  #     Use this if you normally work inside Claude Code native worktrees.
+  worktrees:
+    mode: temp
+  # mode: native  ← uncomment if you use Claude Code native worktrees
+
   # Triggered when a workflow_run fails on a main/master branch.
   # Placeholders: {repo}, {branch}, {run_url}, {workflow}, {status}, {commit}
   on_ci_failure_main:
@@ -85,7 +119,9 @@ behavior:
       3. Push the fix to the branch.
 
   # Triggered when a PR review, inline comment, or unresolved thread arrives.
-  # Placeholder in instruction: {skill}  (replaced with the skill field below)
+  # Placeholders in instruction: {skill}, {worktree_preamble}
+  #   {skill}             — replaced with the skill field below
+  #   {worktree_preamble} — injected automatically based on use_worktree (see below)
   on_pr_review:
     # When true, the instruction must direct the agent to enter plan mode
     # before making any code changes. Strongly recommended.
@@ -94,8 +130,13 @@ behavior:
     # Skill invoked during the execution phase.
     skill: pr-comment-response
 
+    # When true, the PR review work runs as a subagent inside a native Claude Code
+    # worktree (Agent tool with isolation="worktree"). Set to true if you normally
+    # work in Claude Code native worktrees so reviews apply to an isolated copy.
+    use_worktree: false
+
     instruction: |
-      MANDATORY: Enter plan mode first.
+      {worktree_preamble}MANDATORY: Enter plan mode first.
       1. Read every linked thread and summarise what each one asks for
       2. Draft a plan listing the file + change for each thread
       3. Only after the plan is complete, use the {skill} skill to execute
@@ -104,37 +145,33 @@ behavior:
 
       Execution phase:
       1. For each comment thread above, open the link and read full context
-      2. Code comments: apply the fix in a worktree, commit
+      2. Code comments: apply the fix, commit
       3. Questions / style: reply inline with a concise explanation
       4. Use gh-pr-reply.sh --batch to post all replies in one shot
 
   # Triggered when a PR has merge conflicts (mergeable_state=dirty).
-  # Placeholders: {repo}, {pr_number}, {pr_title}, {pr_url}, {head_branch}, {base_branch}
+  # Placeholders: {repo}, {pr_number}, {pr_title}, {pr_url}, {head_branch},
+  #               {base_branch}, {worktree_steps}
+  # {worktree_steps} is generated automatically from behavior.worktrees.mode.
   on_merge_conflict:
     instruction: |
       PR #{pr_number} has merge conflicts with {base_branch}. Act immediately — no confirmation needed.
 
       Use the Agent tool NOW to spawn a subagent with these instructions:
       Resolve merge conflicts for PR #{pr_number} in {repo}:
-      1. git worktree add /tmp/pr-{pr_number}-rebase {head_branch}
-      2. cd /tmp/pr-{pr_number}-rebase && git fetch origin
-      3. git rebase origin/{base_branch} -- fix conflicts, then: git add -A && git rebase --continue
-      4. git push --force-with-lease origin {head_branch}
-      5. git worktree remove /tmp/pr-{pr_number}-rebase
+      {worktree_steps}
 
   # Triggered when a PR is behind its base branch (mergeable_state=behind).
-  # Placeholders: {repo}, {pr_number}, {pr_title}, {pr_url}, {head_branch}, {base_branch}
+  # Placeholders: {repo}, {pr_number}, {pr_title}, {pr_url}, {head_branch},
+  #               {base_branch}, {worktree_steps}
+  # {worktree_steps} is generated automatically from behavior.worktrees.mode.
   on_branch_behind:
     instruction: |
       PR #{pr_number} is behind {base_branch} (no conflicts). Act immediately — no confirmation needed.
 
       Use the Agent tool NOW to spawn a subagent with these instructions:
       Rebase PR #{pr_number} in {repo}:
-      1. git worktree add /tmp/pr-{pr_number}-rebase {head_branch}
-      2. cd /tmp/pr-{pr_number}-rebase && git fetch origin
-      3. git rebase origin/{base_branch}
-      4. git push --force-with-lease origin {head_branch}
-      5. git worktree remove /tmp/pr-{pr_number}-rebase
+      {worktree_steps}
 
 # ── Code style guidelines ─────────────────────────────────────────────────────
 # Free-text block prepended to every PR review notification.