Mention
@agenticmailin any issue or pull request and an AgenticMail agent reads the thread, does the work, and replies — right inside GitHub.
[ hero GIF — see docs/screenshots/hero.gif ]
AgenticMail for GitHub is a mention bot. Drop @agenticmail into a comment on
any issue or PR and the App invokes an AgenticMail agent against that thread.
The agent posts its result back as a comment — usually within a couple of
seconds, after dropping a 👀 reaction so you know it's working.
It also runs automatically on new issues (triage) and new PRs (summary), so your backlog gets a first pass without anyone lifting a finger.
No new infrastructure: the App mounts as a route on your existing AgenticMail deployment and reuses the agent runtime you already run.
- Open AgenticMail on the Marketplace (or jump straight to the install page at github.com/apps/agenticmail).
- Click Install it for free.
- Choose the account/org, then pick All repositories or a specific set.
- Approve the requested permissions (see below) and confirm.
That's it — the bot is live on the repos you selected. The bot proves itself
the first time you @agenticmail it (or open a new issue / PR, which it
will auto-triage and auto-summarize respectively).
[ install screen — see docs/screenshots/install.png ]
| Scope | Access | Why |
|---|---|---|
| Issues | Read/Write | Read thread context, post comments & reactions |
| Pull requests | Read/Write | Summarize PRs, post review-comment replies |
| Metadata | Read | Required by GitHub for any App |
The bot suggests issue labels in a comment — it does not apply or remove labels, close issues, or push code. Triage is advisory in v1.
In any issue or PR comment, type @agenticmail followed by a verb.
Free plan — read + AI-reply commands:
| Command | What happens |
|---|---|
@agenticmail summarize |
Posts a 2-paragraph summary of the thread. |
@agenticmail triage |
Suggests labels, a priority, and similar issues. |
@agenticmail email <addr> |
Sends the thread context to a real inbox via AgenticMail. |
@agenticmail reply <prompt> |
Drafts a follow-up comment from your prompt. |
@agenticmail handoff to <agent> |
Re-routes the request to another agent in your org. |
@agenticmail link related |
Finds and links related open issues by similarity. |
Paid plan — state-changing actions (require an active paid subscription):
| Command | What happens |
|---|---|
@agenticmail close [not planned] |
Closes the issue or PR. Use not planned for non-completed reasons. |
@agenticmail merge [squash|rebase|merge] |
Merges the pull request. Default: squash. |
@agenticmail review |
Posts a formal Pull Request Review (event: COMMENT) with AI-generated feedback. Never auto-approves. |
If a paid command is invoked from a free-plan account, the bot replies with an upgrade prompt linking to the Marketplace listing. No state changes occur.
Notes:
- A bare
@agenticmailwith no verb defaults to summarize. - An unknown verb posts a short help comment — no agent call is made.
- Only the first
@agenticmailmention in a comment is acted on. - Comments from bots are ignored (loop guard).
- New issue opened →
triageruns and posts suggested labels + priority. - New PR opened →
summarizeruns against the description and diff stat.
[ example reply — see docs/screenshots/comment.png ]
The hosted App at github.com/apps/agenticmail
runs on Netlify Functions. The same code can be re-deployed under any other
GitHub App by setting the four env vars below — the function itself is
infrastructure-agnostic (works on any platform that delivers Request/
Response and supports context.waitUntil).
| Route | Purpose |
|---|---|
POST /api/github/webhook |
Receives all GitHub webhook deliveries. |
GET /api/github/health |
Liveness + which secrets are configured. |
GET /api/github/audit |
Operator-only audit log reader (admin-token gated). |
GET /api/github/usage |
Per-installation token + cost aggregator (admin-token gated). |
GET|POST|DELETE /api/github/billing |
Inspect / comp / clear plan records (admin-token gated). |
When you register the App at Settings → Developer settings → GitHub Apps:
- Webhook URL:
https://<your-host>/api/github/webhook - Webhook secret: a strong random string (set it on the App and in env as
GITHUB_WEBHOOK_SECRET). - Permissions: Issues R/W, Pull requests R/W, Metadata R.
- Subscribe to events:
issue_comment,pull_request_review_comment,issues,pull_request,installation,marketplace_purchase.
| Var | Required | Purpose |
|---|---|---|
GITHUB_APP_ID |
yes | Numeric App ID from the App settings page. |
GITHUB_APP_PRIVATE_KEY |
yes | PEM-encoded RSA private key (escaped \n ok). |
GITHUB_WEBHOOK_SECRET |
yes | HMAC secret matching the App's webhook config. |
ANTHROPIC_AUTH_TOKEN |
one of | Claude OAuth token (sk-ant-oat01-…). |
ANTHROPIC_API_KEY |
one of | Classic API key (sk-ant-api03-…). |
ADMIN_AUDIT_TOKEN |
no | Enables /api/github/audit, /usage, /billing. |
SENDGRID_API_KEY |
no | Preferred outbound email path (welcome + ops). |
SENDGRID_FROM_EMAIL |
no | Verified sender address for SendGrid. |
AGENTICMAIL_SEND_URL |
no | Fallback email path (any POST-JSON-compatible provider). |
AGENTICMAIL_API_KEY |
no | API key for the fallback email path. |
AGENTICMAIL_OPS_EMAIL |
no | Recipient for operator-side install notifications. |
The function reads ANTHROPIC_AUTH_TOKEN first; if absent it falls back
to ANTHROPIC_API_KEY. OAuth tokens require model claude-haiku-4-5
or higher — earlier-generation aliases like claude-3-5-haiku-latest
are not visible on the OAuth surface.
Every accepted delivery writes one entry to the github-webhook-audit
Netlify Blob store, keyed by <YYYY-MM-DD>/<delivery-uuid>. User-triggered
mentions are bucketed at 60 per installation per rolling hour — the bot
posts a polite cooldown comment once a bucket is exhausted.
npm install
npm run typecheck # tsc --noEmit
npm run build # compiles to dist/A sample webhook payload for local testing lives at
scripts/fixture-issue-comment.json.
GitHub comment → POST /webhooks/github
├─ verify HMAC (timing-safe)
├─ dedup on X-GitHub-Delivery UUID
└─ enqueue + 202 in <100ms
│
async worker
├─ 👀 reaction on the trigger comment (~1s)
├─ parse mention → verb + args
├─ fetch thread context via Octokit
├─ invoke agent runtime (inject-message)
└─ post the agent's reply as a comment
The webhook never blocks on agent work — GitHub gets its 202 immediately and
all the real work happens off the request path. See design.md
for the full API contract.
- HMAC-SHA256 verification on every webhook, constant-time compared.
- Delivery-UUID dedup (5-min TTL) so GitHub retries never double-post.
- Short-lived (~60 min) per-installation tokens, minted on demand from the App's private key — never persisted.
- Per-installation rate limiting (60 user-mentions / hour) to cap abuse impact.
- Bot-authored comments are ignored on inbound (no self-mention loops).
This repo eats its own dog food — AgenticMail is installed on
agenticmail/github-app, so every contribution gets the same automated
treatment any user does. Useful while filing issues or sending PRs:
Open one the usual way (Issues → New issue). Within ~15 seconds the bot
will auto-triage it: a comment lands suggesting labels, a priority, and
whether it looks like a duplicate of anything in the thread. Treat that as
a starting point — the bot suggests labels, it doesn't apply them. If
the triage is off, ignore it and re-state the bug.
You can also call the bot yourself in any comment:
@agenticmail summarize # re-summarize after a long discussion
@agenticmail link related # find related open issues
@agenticmail triage # re-triage after the description changes
-
Fork, branch, commit, push, open the PR.
gh pr createworks fine. -
The bot auto-summarizes every new PR within ~15 seconds. The summary pulls in the diff from up to 20 changed files (first 40 lines of each patch) so the description doesn't have to do the heavy lifting.
-
In any PR comment, you can request a deeper read:
@agenticmail review # AI-generated PR review (COMMENT event) @agenticmail summarize # re-run the summary @agenticmail reply explain the rate limiter change in plain Englishreviewposts a formal Pull Request Review withevent: COMMENT— it never auto-approves or requests changes. A human still has to merge.
The bot is rate-limited to 60 mentions per installation per rolling hour. If you hit it, the bot posts a polite cooldown comment with the ETA — wait for the reset, then continue.
Just ignore the comment and reply normally — the bot's reply is a draft, not the source of truth. If a comment is misleading enough to need removing, leave a 👎 reaction so we can audit those cases.
| Capability | Available on this repo |
|---|---|
| Summarize, triage, reply, email, handoff, link | ✅ Free, always on |
| Auto-triage on new issues / auto-summary on new PRs | ✅ Always on |
| Close issues or PRs | ✅ (paid-plan-only feature; agenticmail org is comped) |
| Merge PRs | ✅ — but the bot never merges without an explicit @agenticmail merge |
| Review PRs | ✅ — posts a COMMENT review, never an auto-approve |
If you'd rather the bot stay out of a specific thread, just don't
@agenticmail it. The auto-triage / auto-summary still fires once on
open — there's no per-thread opt-out yet.
- agenticmail/send-email-action — send email straight from a GitHub Actions workflow step. Different tool, same family: that's for CI pipelines, this is for issue/PR conversations.
MIT © AgenticMail