Architecture reference
The engine is one Lambda (the receiver), one DynamoDB table, a one-minute EventBridge schedule, and one kind of unattended Claude Code session: a cloud routine that investigates a batch of issues and, for the findings the receiver’s gate approves, writes the fix as well. This document walks the pipeline end to end and then covers the security model that makes the unattended parts safe to run.
The receiver
Section titled “The receiver”receiver/ is a single Lambda behind a Function URL. handler.py routes:
| Route | Caller | Purpose |
|---|---|---|
POST /sentry |
Sentry | Issue alert webhook, HMAC-verified |
POST /bot |
Azure Bot Service | Teams bot messages (JWT-verified) |
POST /findings |
The investigator session | Findings document for a fired batch; the response vends any autofix grants it earned |
POST /findings/probe |
The probe session | Configuration probe report |
POST /autofix-result |
The same session’s fix phase | Outcome callback, capability-token auth |
POST /issues |
The investigator session | One named issue operation, tracking-token auth; the receiver makes the GitHub write, or runs the duplicate search, as the App |
GET /health |
Operators | Liveness |
The same Lambda is also invoked directly (not over the URL) by the EventBridge rule that drives the sweep, so the scheduled path is not reachable from the internet.
State lives in one DynamoDB table (receiver/store.py): posted alert cards and their Teams message ids, the pending-investigation queue, dedupe and skip caches, autofix dispatches and their callback tokens, and tracking grants with a record of each issue operation made under them.
The issue proxy (issues.py, with the route in handler.py and the calls in github_app.py). While issues.enabled is on for a batch’s environment, the /findings response carries a tracking block beside autofix: one grant per delivered result, each a tracking id and a token stored only as its hash, scoped to that alert’s thread and dead 30 minutes after findings, or 90 when the result also earned an autofix grant, whose fix phase comes first. A session that ends a finding without a pull request calls POST /issues with one of five named operations: file_issue, comment, reopen, set_fields, add_to_project. A sixth, search, runs GitHub’s issue search as the App with a read-only token and answers with the best matches; the receiver adds the repository and issues-only qualifiers itself, after turning every colon in the session’s terms into a space so they can carry no qualifier of their own, and the search spends only a per-alert cap. The receiver checks the request against fixed rules, checks that a numbered issue is an issue in target_repo (never a pull request, never one transferred away), claims the per-alert and per-day caps, and makes the write as the GitHub App with a token minted for that one operation, redacting the text and closing it with a line naming the Sentry issue. One new issue, duplicate comment or reopen becomes the alert’s tracking issue, and that outcome’s link is posted in the alert’s thread; set_fields and add_to_project touch only the issue the alert itself filed. A resent operation is answered from its stored record instead of being written twice. When a grant expires with no tracking outcome, the sweep posts a notice in the thread, so an alert a session never filed still shows.
Alert to Teams card
Section titled “Alert to Teams card”POST /sentry verifies the webhook signature, parses the alert (models.py), renders an Adaptive Card (cards.py), and posts it to the configured Teams channel through the receiver’s own bot identity (bot.py, an Entra app registration plus an Azure Bot). Posting directly through a bot identity means message ids come back synchronously, which is what makes threaded follow-up replies (findings, autofix outcomes) possible.
The investigation pipeline
Section titled “The investigation pipeline”Gate (investigation.py). An alert is worth investigating when its kind is investigated (warning level and above, plus the N+1 Query and N+1 API Call performance issues Sentry files at info; models.investigated_kind decides this and the card’s “not auto-investigated” footer alike, so the two cannot disagree), in an investigated environment, and carries a release that resolves to a commit SHA (for projects where the release is the SHA, a 40-char hex check; anything else means something changed upstream and the alert is skipped rather than investigated at branch HEAD). Eligible alerts are enqueued with a debounce so that a burst of related issues becomes one batch. The enqueue is a conditional write keyed by issue, environment, and release, and that key is the skip cache: a repeat alert on an unchanged release (frequency rules re-fire for a hot issue) finds the row and replies to its own card with a link to the thread that holds the findings, quoting whichever of urgency, confidence, fixability, and intent the row recorded. If the earlier attempt ended failed, the repeat requeues the row under the new card instead, bounded by MAX_REQUEUES, and the sweep announces the retry there.
Sweep (sweep.py). Every minute, the sweep groups due pending issues per project and release (up to max_batch_issues), respects the per-sweep and daily fire caps, and fires one routine session per batch. It also enforces deadlines: a batch whose findings never arrive within deadline_seconds is failed loudly into the thread rather than left hanging.
Fire (routines.py). A fire is POST /v1/claude_code/routines/{id}/fire with a JSON payload of exactly five fields: project, issue_ids, release, batch_id, reply_token. The payload is capped at 65,536 characters by the API, which is why the engine sends issue ids only and lets the session fetch event detail itself. The API has no idempotency key, so the receiver owns dedupe. On 429, Retry-After decides the response: a short delay is read as the daily routine-run cap and earns one bounded retry; a long one is read as subscription-window exhaustion and is skipped and logged (usage credits are off, so exhaustion rejects rather than bills).
Investigate (prompts/investigator.md). The session checks out the target repo at the release SHA, investigates each issue in the batch, and posts a findings document to the receiver’s /findings endpoint, authenticated by the reply_token minted for that batch. Its GitHub reads beyond the checkout are issue reads through the platform’s built-in GitHub tools, which act as the operator; the routine withholds every other tool of that server, write tools included (see Runbooks).
Findings (findings.py). The receiver validates the document shape, redacts secret-shaped strings, renders a reply card, and posts it into the original alert’s thread. It accepts schema versions 1 to 4. Version 3 adds an urgency rating to every result (urgent, high, medium, or low, rated by the session against the target repository’s own priority meanings); the receiver checks it is one of those four words and otherwise passes it through untouched, recording it on the investigation row beside confidence and fixability and putting it first on the reply card’s status line. No receiver decision reads it. Version 4 adds an intent object to every result: settled, a boolean saying whether the correct behavior is already decided somewhere authoritative (the product code or its comments, a merged pull request, a design doc, a repository rule), and source, the place that decides it. The receiver checks the shape, records the intent on the row as settled or unsettled, shows it on the status line after fixability, and puts a settled intent’s source first in the card’s details, where a reviewer checks the fix against it. A settled intent with an empty source still parses: naming the source is the gate’s rule, so the slip costs the fix attempt rather than the batch’s findings. A document in an older version is delivered the same way without the lines it lacks, and logs FINDINGS_SCHEMA_OUTDATED, which is counted and never alarmed.
The autofix pipeline
Section titled “The autofix pipeline”Autofix runs inside the investigation session, not after it. The reason is a property of the runtime rather than a preference: the receiver can answer a session’s request, but it cannot send a message to a session already running. The HTTP response to POST /findings is therefore the only channel it has, and everything the fix phase needs has to travel back down it.
Gate (autofix.py). Evaluated per result as the findings are delivered. A finding proceeds to autofix when autofix is enabled, the project is on the allowlist (an empty allowlist opts in every project), the findings document is schema v2 or later, the result is investigated, its confidence and fixability each clear the configured minimums, its intent is settled and names a source, no cited file matches a forbidden or excluded path, no fix has already been attempted for this issue in this environment on this release, and the daily pull-request cap has budget left. Checks run cheapest first and the first failure wins, so a decline names one reason and appends it to that finding’s reply card. Intent has no threshold and no operator setting. Fixability measures how contained a change is, not whether the current behavior is a mistake, and a deliberate failure can usually be worked around by a change smaller than the one that meets it; so an unsettled intent declines (intent unsettled) however small the fix, as does a settled one with no source (intent source not named). A v2 or v3 document predates the rating and fails closed with intent not rated, after the confidence and fixability checks, so a finding that would have failed those still names them. The single exception is autofix being switched off entirely, which says nothing at all: with the kill switch off, no thread carries an autofix line.
Grant. A passing finding earns a grant: a dispatch id, a one-time callback token (stored hashed, scoped to that single dispatch), and the files the finding cited. The /findings response carries the repository, the base branch, the callback URL, and one grant per approved finding, and nothing else. No credential travels down it.
Fix (prompts/investigator.md, step 8). The same session works each grant independently: check out the base branch and record the commit it resolved to, diff the cited files against the release it investigated and abort if that drift invalidates the diagnosis, re-verify the root cause at this checkout, write the fix and a test that fails without it, run the narrowest relevant test command, then compose the pull request title and body. It then POSTs fix_ready to /autofix-result with the base commit, the fix as a patch (git diff --binary output against that commit, new files included, base64-encoded), and the title and body. A patch’s size follows the change rather than the files it touches, so a few lines changed in a large generated file travel as a few lines. The receiver still accepts the original form, every changed file as whole text, from a session that sends it. Every path through that phase reports exactly once, including the paths that stop early.
Open (handler.py, github_app.py). On fix_ready the receiver validates the payload before anything else: exactly one of files and patch, a full commit SHA, at most twenty changed files, plain repository-relative paths (both sides of a rename), none matching a forbidden or operator-excluded pattern, no mode but a regular or executable file, a bounded size (512 KB of whole-file content, or a 4 MB patch), and a one-line title. A patch is parsed in full at this point (patch.py), and anything that is not plain git diff output is refused. It then claims the dispatch record as opening under a three-minute deadline, mints one GitHub App installation token scoped to target_repo and to contents: write plus pull_requests: write, and works through GitHub’s API under one time budget: it reads the base branch and confirms the base commit is on it, reads the base commit and its tree, and checks the tree’s entries for every path the fix touches: no fix replaces or writes through a symlink, a submodule, or a directory. For whole files it then creates a blob per file (keeping the executable bit on a file that had one). For a patch it confirms each file’s base blob is the one the patch names, reads each base file the patch modifies, applies the hunks at exactly the lines they name with no fuzz or offset, checks the result against the blob id git wrote on the patch’s index line, and uploads it; a deletion, a pure rename, or a mode change reuses the base blob. GitHub builds blobs only from whole content, so this is where a large file’s size is paid, receiver to GitHub, bounded by a 48 MB cap on the base files one patch may rewrite. Then it creates a tree that inherits the base commit and overrides or deletes only those paths, a commit whose parent is the base, a branch named from the short id and the dispatch id, and the pull request against the base branch. The commit message is the session’s title and the pull request body is the session’s body, each closed by a Fixes <short id> line that Sentry reads to resolve the issue in the first release carrying the fix. The short id comes from the dispatch record rather than the payload, and it goes on both so the line survives a squash, rebase, or merge commit alike. The App is the author because the App’s token is the only credential that ever writes to GitHub.
Close. The record settles to pr_opened with the URL, or to failed with the reason (for a patch the base tree refused, which file and why), and the thread is told either way; the callback’s HTTP response carries the same outcome, so the session has nothing further to send. A grant that never calls back is failed by the sweep once its hour is up, and an opening record the receiver never settled is failed once its three minutes are up, with a reply that names the receiver rather than the session. Every pull request waits for a human reviewer; nothing merges automatically.
Track (prompts/investigator.md, step 7). A finding that ends without a pull request is filed in the target repository’s issues: every result with no grant, which includes every partial or failed investigation, right after the findings response, and every granted result whose callback carried any status other than fix_ready, right after that callback. A fix_ready result is never filed, because a pull request the receiver could not open is the receiver’s failure rather than a defect in the repository. The session searches the repository’s issues through the receiver’s search operation, opens the plausible matches with its one read tool, judges the best match a duplicate, a related issue, or neither, and drafts from the repository’s own issue conventions: the files issues.conventions names, which the prompt carries from the moment it is pasted. It then asks the receiver’s /issues route for each write by name, presenting the tracking token its result was issued with the findings: a comment on a duplicate, a reopen of a closed duplicate whose fix the investigated release already contains, or a new issue with its Priority, its place on the board, and a comment on each related issue. The receiver performs each write as the App and links the issue in the alert’s thread.
Security model
Section titled “Security model”The trust boundary and every control around the unattended sessions have their own page: Security model.
Infrastructure
Section titled “Infrastructure”infra/ is a self-contained CDK v2 app deploying one stack: the receiver Lambda and Function URL, the DynamoDB table (retained on stack delete), the EventBridge sweep rule, the wiring to the SSM parameters, and the alarms. Every failure the receiver can detect in its own pipeline logs a marker that a metric filter turns into an alarm on one SNS topic, listed in Runbooks. The topic emails aws.alarm_email, and when aws.alarm_ntfy_server is set, a second, standalone function subscribed to it publishes each alarm to an ntfy topic. That function imports nothing from the receiver and can read only the one parameter holding its topic. Deploy instructions are in infra/README.md.