umbrella: trigger Codev from GitHub directly via @codev mentions (design space)

[amrmelsayed]

Umbrella / discussion issue. Frames the design space for letting users trigger Codev actions from GitHub directly via @codev <command> mentions in issue and PR comments, similar to other AI-assistant GitHub integrations. The purpose is team discussion of trade-offs, not a committed plan. Each architectural approach preserves or trades different properties; the right answer depends on which trade-offs the team finds acceptable for which audience.

Context

Other AI-assistant tools support @<assistant> <command> mentions in GitHub issues and PRs that trigger automated actions. Codev's current flow requires the architect to be at their machine to drive afx spawn, afx send, porch approve, etc. A GitHub-mention pathway would let team members (or the architect themselves, from a phone, browser, or anywhere away from the machine) trigger Codev actions from inside GitHub directly.

This is meaningful for three audiences:

1. Team members who notice something and want to ask Codev to act on it (file a bugfix, run a research pass, surface status) without driving the architect's machine.
2. The architect themselves, when they're away from their workspace but want to kick off non-interactive work (autonomous protocols, queries, gate approvals).
3. External contributors and adopters, where the architect-machine model is friction and GitHub is where the conversation naturally lives.

What the pattern would look like

User types in any issue or PR comment:

@codev pir

or

@codev status

or

@codev approve plan

Something runs, the issue thread gets a status comment back, and at some point a builder PR materializes (if the command was a spawn). The "something" is the load-bearing architectural decision.

Architectural options

Four approaches sit on a tradeoff axis between operational complexity and what's enabled.

Option A — Hosted Codev service

Codev runs as a hosted endpoint at some shared URL. GitHub webhook posts to it. The hosted service spawns the requested action and bills back per use.

• Pros: Zero-config UX. Users install a GitHub App, write @codev, get a response. Real-time. Works for users who don't run a local Tower.
• Cons: Multi-tenancy. Billing. Secrets management. Hosting infrastructure. Significant ongoing engineering and operational lift, including legal and reliability surface.
• Verdict pre-discussion: too heavy for current Codev shape; would change the project's distribution model from "self-hosted CLI" to "hosted service." Out of scope unless someone really wants to take that direction.

Option B — Self-hosted webhook receiver

Each user runs their own webhook endpoint locally (cloudflared, ngrok, a small reverse-tunnel). GitHub posts to their personal URL on a mention. Their local Tower receives the webhook and acts.

• Pros: Real-time response. Local Tower stays the source of truth. No hosted service.
• Cons: Each user must expose a public URL. Webhook secret rotation, IP filtering, payload validation, replay protection. Not zero-trust; the URL becomes an attack surface.
• Verdict pre-discussion: works but most users won't set up a public webhook endpoint. Tradeoff weighs against this for the general case.

Option C — GitHub Actions

Ship a .github/workflows/codev.yml via codev-skeleton/. The workflow triggers on issue_comment and pull_request_review_comment events, parses for @codev <command>, and runs the requested action inside the runner. The runner posts back to the issue thread.

• Pros: No public endpoint. No hosted service. Self-contained per repo. Familiar pattern. GitHub provides authentication and webhook delivery for free.
• Cons: Limited to commands that run to completion inside a runner (autonomous protocols, status queries). Interactive protocols (PIR, SPIR) need human gates that the runner can't satisfy. Constrained by Actions runtime limits and minutes budget. Result of work happens inside the runner, not on the architect's machine.
• Verdict pre-discussion: strong for autonomous and read-only commands. Doesn't cover interactive flows.

Option D — Label-as-wire (async polling)

A small GitHub Action listens for @codev mentions and, instead of acting directly, adds a label to the issue: codev:request:pir, codev:request:status, etc. The architect's local Tower polls for these labels and acts when next online. On action, the label transitions: codev:request:pir → codev:in-progress:pir-1024 → removed on completion.

• Pros: No public endpoint. No hosted service. Works with the existing local-Tower model unchanged. Scales naturally to multi-architect (route by label content: codev:request:pir:@bob → Bob's Tower picks it up). Decouples trigger from execution time.
• Cons: Async only. Goes stale if the architect is offline for long stretches. Doesn't suit "I want a response right now" UX. Polling overhead on the local side (cheap but real).
• Verdict pre-discussion: best fit for the interactive-protocol case where the work needs the architect's machine anyway.

Recommended starting shape — hybrid of C + D

The simplest path that does something useful immediately:

• Autonomous commands (@codev maintain, @codev research, @codev bugfix, @codev status, etc.) run inside the GitHub Action via Option C. They don't need human gates, they fit the Actions runtime budget, and the result posts as a comment in the issue thread. No architect-machine involvement needed.
• Interactive commands (@codev pir, @codev spir) become labels on the issue via Option D. The architect's local Tower watches for the label and spawns the builder when next online, swapping the label to codev:in-progress:<builder-id> once work starts. When the builder reaches a gate, a comment posts to the issue thread.

This splits the trigger surface by what kind of work is being asked for:

• Read-only and autonomous → instant feedback (Action does it)
• Interactive (needs gates) → queued for next architect availability (label routing)

The architect-machine still drives the load-bearing interactive work. Anyone can trigger non-interactive work without needing the architect's machine.

Commands worth supporting in an MVP

Not exhaustive — the team should pick which subset matters for first cut:

Command	Where it runs	Notes
@codev status	Action	Reads current builder state for the issue from the GitHub label and recent commits; posts a one-comment summary.
@codev spawn <protocol>	Action for autonomous, label for interactive	Same spawn the architect would run locally, modulo the human-gate surface.
@codev approve <gate>	Action	Calls the equivalent of porch approve <id> <gate> via the GitHub label state.
@codev cleanup	Action	Equivalent of afx cleanup --project <id> from the issue context.
@codev help	Action	Posts the supported command list back as a comment.

Open decisions for team discussion

These are the calls where preferences will affect the UX. Initial leans below; not committed.

1. Trigger access control

Who's allowed to trigger Codev from GitHub?

• Anyone with comment access. Public repo nightmare; trivially expensive abuse vector.
• Only collaborators / org members. The natural default. Validates comment.user.permission ≥ write.
• Allow-list per repo. Maintainers configure who can @codev. More work but tighter.
• Lean: collaborators / org members by default; allow-list as an override in .codev/config.json.

2. Acceptable lag for interactive commands

How long can a user wait between @codev pir and the bot acknowledging?

• Sub-minute — requires webhook or aggressive polling (1-2min cycle). High polling cost.
• Within an hour — polling every 5-10 minutes is fine.
• End-of-architect-session — label scan once per architect-online-session; no polling between sessions.
• Lean: polling-cycle configurable per architect, default 5min.

3. Trigger surface scope

Where does @codev get parsed?

• Issue comments only — simplest.
• Issue comments + PR comments + PR review comments — full coverage; more entry points.
• Also issue body itself (mention in the opening body) — risk of accidental re-trigger on edits.
• Lean: issue comments + PR comments + PR review comments. Skip issue body.

4. Result-posting style

How does the action surface its work in the thread?

• Single status comment, edited as state changes — clean thread.
• One new comment per state transition — noisier but more visible.
• A status check on the PR + a single comment — combines PR check infrastructure with a thread anchor.
• Lean: single editable status comment per request, plus PR check when a PR is in scope.

5. Multi-architect routing

How does an explicit-architect mention map to the label routing?

• @codev pir → routes to the configured-default architect (main if present).
• @codev pir:@bob → routes specifically to Bob's Tower via label codev:request:pir:@bob.
• @codev:bob pir → alternative shape for the same routing.
• Lean: pick :@bob suffix syntax; matches Codev's existing architect:<name> precedent in afx send.

What this isn't

• Not a hosted service. Codev stays distributed across users' machines / runners.
• Not a replacement for afx send / direct CLI use. Both surfaces coexist.
• Not a path to fully autonomous "Codev runs my project without me" — interactive protocols still need human gates, just triggered async.
• Not for multi-repo orchestration (a @codev in repo A shouldn't drive work in repo B unless the user has explicitly configured a cross-repo binding).

What this would change

• codev-skeleton/.github/workflows/codev.yml — new workflow that the skeleton ships with codev init.
• A small new agent-farm command that watches for the request labels and dispatches accordingly. Plumbed similarly to afx tower / afx workspace.
• A GitHub App or PAT setup step documented in the README for the writeback / label-mutation operations.
• .codev/config.json additions for access control, polling cycle, multi-architect routing preferences.

Why a SPIR (if it gets built)

The work spans multiple surfaces (GitHub Actions, agent-farm command, config, distribution) and involves real security decisions (trigger access control, secret management for label writes, abuse prevention). Multi-phase development with consultation is the right protocol if this advances past discussion.

Related

• Inter-architect messaging (existing) — afx send architect:<name> is the in-Codev precedent for the @codev:<name> routing shape proposed in §5.
• porch + vscode: write GitHub Project Status updates as porch advances phases (bidirectional Project integration) #817 — outbound GitHub Project Status integration — overlapping plumbing (label writes, GitHub-side state). Worth deciding whether they share an underlying GitHub-mutation helper.
• afx: handoff / pickup commands for transferring in-flight builders between team members #1008 — afx handoff / pickup — the multi-architect routing infrastructure (spawnedByArchitect lookups, label-keyed dispatch) directly informs §5 here.
• Multi-architect coordination (Multi-architect coordination layer for codev/afx (roster · board · dedup-at-spawn · lifecycle · bounded state · checkout isolation) #984) — the dispatch / queue infrastructure for routing GitHub-triggered work to the right architect connects to the roster / ledger machinery in §3 of that spec.