Overlay

Preview overlay

Every Destesi preview is fronted by a small reverse proxy that injects a shell UI at /.destesi/*. Reviewers get a summary modal on first load, an agent chat that can edit + commit + push back to the PR, and live dev tools — without touching the app’s code.

What’s in it

Surface	Shortcut	What it’s for
Summary modal	—	First-load dialog: PR title, auto-generated 2-3 sentence summary, files changed.
Preview agent	Cmd+Shift+A	Chat that reads, edits, git commits, and git pushes back to the PR branch.
Pod logs	Cmd+Shift+L	Live tail of the runner + compose stack.
Inspect element	Cmd+Shift+I	Pick a DOM node from the iframe; the agent gets it as context.
Network	Cmd+Shift+N	Captured fetch/XHR from the app frame (status, duration, method).

Change-summary modal

Shown once per commit SHA. Meant to orient a reviewer before they click around — what did this PR change and where. Closes on backdrop click, Got-it button, or Escape; dismissal is stored in localStorage keyed by commit SHA so a fresh push re-opens it.

Contents

• Title line — #42 — PR title (falls back to PR title alone, then generic).
• Summary — 2-3 sentence Anthropic-generated description of the PR’s intent. Generated server-side against the PR diff; cached on the preview row after first generation.
• Fallback body — first 500 chars of the PR description, shown only when the AI summary isn’t available.
• Technical details — collapsible <details> with per-file add/delete counts.

Enabling the AI summary

The summary is optional. If ANTHROPIC_API_KEY is unset on the API, the modal still renders — it just falls back to the PR body. Model: claude-sonnet-4-6. One generation per commit SHA; result is persisted in the pr_summary column.

Preview agent

A small chat panel that can actually change the code. Open it with Cmd+Shift+A from inside a preview, describe a fix, and the agent will propose edits, run git commit, and git push to the PR branch. GitHub Actions then redeploys the preview against the new commit.

Tools the agent has

Tool	Effect
list_files	Walk the repo; returns entries rooted at the repo (directories end with /).
read_file	Read up to 50 KB of UTF-8 from a repo-relative path.
edit_file	Unique-match string replacement — errors if old_string isn’t found or appears more than once. Forces the model to read before guessing.
git_diff	Working-tree diff; use after edits to sanity-check before committing.
git_commit	git add -A + commit with the user’s message; returns the new SHA.
git_push	git push origin HEAD; triggers the PR’s GitHub Actions, which redeploys the preview.

The Commit shortcut button

Below the chat composer there’s a Commit button. Clicking it sends a canned prompt — “Please commit the pending changes with a one-line message describing them, then push.” — so you don’t have to retype the shipping step after the agent edits.

Commit attribution

Commits are authored as destesi-preview-bot <bot@destesi.io> and carry:

<your one-line message>

Applied via destesi preview chat.

Co-authored-by: Jane Doe <jane@company.com>

The Co-authored-by line is the human who was chatting — pulled from their destesi user profile, not from the GitHub installation, so it survives workspace-wide token rotation.

How push auth works

For github-source previews the runner does a real git clone (depth 50, .git intact) using a GitHub App installation token injected as PREVIEW_GITHUB_TOKEN:

git clone --depth 50 --branch <pr-branch> \
  https://x-access-token:$PREVIEW_GITHUB_TOKEN@github.com/owner/repo \
  /workspace/src/repo

So git push Just Works with the same token — no personal access tokens, no SSH keys.

Not supported for tarball previews

Tarball-source previews (dst preview create --from-dir …) extract without .git, so git_commit / git_push return errors. read_file / edit_file still work for scratch iteration.

A typical review → fix → ship loop

1. Reviewer opens the preview URL, sees the summary modal, clicks through.
2. They click around the app and spot a typo / wrong label / off-by-one copy change.
3. Press Cmd+Shift+A to open the preview agent. Optionally use the inspect element tool first to pin the exact DOM node.
4. Describe the fix in natural language: “change the button text from ‘Sign up’ to ‘Create account’.”
5. The agent runs list_files / read_file / edit_file, then reports the diff.
6. Reviewer clicks the Commit button → agent git commits + git pushes to the PR branch.
7. GitHub Actions fires on synchronize. dst preview upsert redeploys the same preview on the new commit. The summary modal re-appears on the next reload (new SHA).

Guardrails

• All file paths are validated — absolute paths, parent traversal (..), and paths outside /workspace/src/<repo>/ are rejected before they reach the runner.
• edit_file uses unique-match semantics — if the old_string appears 0 or >1 times the call fails, forcing the agent to re-read and disambiguate before writing.
• Push auth is the PR’s GitHub App installation token, so branch-protection rules, required reviews, and CODEOWNERS all still apply — the agent can’t bypass them.
• Every turn is stored against a session id on the preview; the full transcript is auditable via the web UI and the /v1/agent API.
• The agent can only run the file and git tools listed above. No shell, no arbitrary exec, no package install.

Other overlay tools

Hidden behind the same rail as the agent chat, sharing the panel host. No extra install — they’re part of every preview.

• Pod logs (Cmd+Shift+L) — streams the runner + compose stderr/stdout via the API’s log proxy. Useful for diagnosing build failures without leaving the preview.
• Inspect element (Cmd+Shift+I) — pick a DOM node from the iframe; the shell captures it as context so the agent knows which element the reviewer is talking about. Falls back to a rough CSS selector if the host app doesn’t expose stable ids.
• Network (Cmd+Shift+N) — taps fetch / XMLHttpRequest from the app frame and lists them with status + timing. Great for isolating a 500 without opening the browser DevTools.

Related env vars

Variable	Effect
ANTHROPIC_API_KEY	Server-side. Enables both PR summary generation and the agent chat. Unset → summary modal renders without AI summary; agent replies with a setup hint.
AWS_BEARER_TOKEN_BEDROCK	Server-side. Default LLM provider is Bedrock; this token is required when DESTESI_AGENT_PROVIDER is unset or set to bedrock. Pair with AWS_REGION.
DESTESI_OAUTH_STATE_SECRET	Overlay-side. Required for OAuth passthrough; unrelated to the agent but the same overlay hosts both.
PREVIEW_GIT_EMAIL	Override the bot commit author email. Default: bot@destesi.io.
PREVIEW_GIT_NAME	Override the bot commit author name. Default: destesi-preview-bot.

Next

GitHub Actions workflow

OAuth passthrough

Env templates

Troubleshooting