Use Show Pages

Use Show Pages

When a visual page would help the user understand a problem, plan, process, result, or complex information more clearly, use Show Pages. They are useful for diagrams, flowcharts, mind maps, timelines, architecture maps, comparison views, dashboards, visual reports, interactive explanations, and small prototypes.

Each Agent Session has one Show Page. Get this session's page directory:

vibe show path

Check status:

vibe show status

Change visibility:

vibe show update --visibility public vibe show update --visibility private vibe show update --visibility offline

For more usage details, run vibe show --help or a subcommand help such as vibe show update --help.

Agent-readable representation

• Every Show Page URL is agent-readable without page-specific code: request the same private or public URL with Accept: text/markdown to receive its rendered Markdown representation.
• Author semantic HTML so that representation stays dense and useful: use headings for sections, lists for sequences or groups, and <table> for genuinely tabular data.
• Add data-agent-hidden to visual-only or sensitive-to-representation elements that should be omitted from Markdown. Add agent-note="..." when an element needs short agent-only context; the note text is preserved in the representation.

Show Page annotations & reverse marks

• Users can annotate your Show Page; each annotation arrives as a chat message tagged [show-annotation] with its event id. Some messages end with a ready-to-run reply command — whether to reply on the page or respond by editing the page content is your call, per scenario.
• After reworking a page area you may leave a short callout: vibe show mark <selector-or-anchor> --message '...' (same target replaces), or an agent-note="..." attribute on elements you author. Marks retire once read — leave at most 1-2 per turn.
• Inspect/withdraw: vibe show marks / vibe show unmark <id|target> ...; toggle the user's annotation mode: vibe show annotate --on|--off [--mode smart|screenshot].

For live runtime, visibility, and URL availability, treat vibe show status and the relevant command output as authoritative.

Public server-to-server handlers

For an explicitly published POST endpoint that authenticates a non-browser sender, read Public server APIs before authoring its .show-api.json declaration. Trusted handler code owns sender authentication; the declaration does not publish a page or install/start its Runtime.

Show Page workspace history

These rules apply only to this Session's Show Page workspace and its Avibe history. Avibe manages page checkpoints automatically; do not create versions manually for page edits.

Before operating on history, run vibe show status --json. Use its path as <show-workspace> and inspect history.mode, history.checkpointing_active, and history.git_dir. Status is read-only; it does not initialize a repository. If checkpointing is inactive, do not assume new edits have automatic checkpoints or start managing Avibe history yourself. Existing history can still be inspected and restored when requested.

When history.mode is managed:

• Before using git -C, check that git -C <show-workspace> rev-parse --absolute-git-dir resolves to history.git_dir. If it does not, do not use an enclosing repository or initialize one in its place.
• Read freely with git -C <show-workspace> status / log / diff / show.
• Restore files with git -C <show-workspace> restore --source=<ref> -- <path>. When checkpointing is active, Avibe records the restored files in a new forward checkpoint. Do not move HEAD, switch branches, rewrite history, run gc, or commit checkpoints yourself, regardless of checkpoint availability.
• Adding remotes, pushing, or publishing the page requires the user's corresponding authorization.

When history.mode is self-managed, the workspace has the user's own Git repository, separate from Avibe's shadow history:

• git -C <show-workspace> addresses the user's repository, not Avibe history. Do not commit or modify that repository to manage Avibe page checkpoints.
• Separately entrusted repository work follows the user's mandate; page checkpoint rules do not prohibit it.
• Only when the user asks to recover from Avibe history, use the returned history.git_dir as <shadow-git-dir> with explicit paths: git --git-dir=<shadow-git-dir> --work-tree=<show-workspace> log to inspect, and git --git-dir=<shadow-git-dir> --work-tree=<show-workspace> restore --source=<ref> -- <path> to restore files. Do not commit to or otherwise mutate the shadow history.

Guidance:

• New Show Page workspaces are managed React/Vite apps that start as a clean "being generated" placeholder page (what the user sees while you build) plus a minimal file-based router (src/router.tsx) and one example page. When that router is present, add a route by creating a file under src/pages/ — a folder becomes a nested path segment and a [param] file a dynamic segment — and customize the layout in src/App.tsx, styles in src/styles.css, and optional api/*.ts handlers. The starter is only a starting point, not a required structure: replace the placeholder with the real page, add or remove pages, and organize them however fits the app (flat, sections, or nested). Built-in UI is available to import, e.g. @/components/ui/card, @/components/ui/button, @/components/ui/badge.
• An older Show Page with no src/router.tsx is a single-page app that renders src/App.tsx directly. There, edit src/App.tsx (or adopt the router scaffold: add src/router.tsx + src/pages/ and render it from App.tsx) — do not just drop files under src/pages/, since nothing would route them.
• Treat index.html and src/main.tsx as the runtime-owned app shell — you never edit them to add a page, and should not replace them unless you are repairing the shell.
• Hot reload is available while /show/<session-id>/ is open. Users will see page changes live. Prefer component-level changes that preserve React state.
• Built-in UI uses the standard shadcn aliases: import components from paths such as @/components/ui/button, @/components/ui/card, @/components/ui/badge, @/components/ui/dialog, @/components/ui/input, and @/components/ui/progress, and import cn from @/lib/utils.
• Tailwind CSS v4 utility classes are built in and work in any className, including to restyle the built-in @/components/ui/* components (a utility overrides the component default). src/styles.css is the CSS entry and must keep @import "tailwindcss"; and @import "@avibe/show-ui/theme.css"; at the top. Theme with standard shadcn variables such as --background, --foreground, --card, --primary, --muted, --border, --ring, and --radius; values are complete CSS colors usable directly through var(...). Override the same variables under .dark or [data-theme="dark"] for dark mode. Do not use runtime-prefixed private variables.
• Prefer the built-in UI primitives over hand-rolled controls. They include Show Page motion for changed text, numbers, badges, cards, and progress without extra animation calls.
• Optional server handlers live under api/ and run only when requested. Export functions named like HTTP methods, for example export async function GET(request) { return Response.json({ ok: true }) }.
• Design for user understanding, not just for moving text onto a webpage. Choose the visual form that best helps the user inspect, compare, confirm, and continue the discussion.
• Use diagrams or mind maps for relationships, flowcharts or state machines for processes, timelines for sequences, charts or dashboards for metrics, and side-by-side views for tradeoffs.
• Make the page visually polished: use clear hierarchy, spacing, typography, contrast, and consistent components. Avoid rough default-looking pages.
• Give the app a recognizable icon so it stands out in the Dock and App Library: drop a public/favicon.svg (or favicon.svg at the workspace root) and it is picked up automatically, or add <link rel="icon" href="./favicon.svg"> to index.html (an icon edit to the shell is fine).
• Make the page work reasonably on mobile because users may open links from an IM app on their phone.
• Prefer React component implementations. Useful visualization libraries include React Flow, Mermaid, Markmap, Chart.js, and Cytoscape.js.
• Keep pages private by default. Publish publicly only when the user asks for a shareable or public link.
• Do not publish secrets, credentials, private logs, or sensitive user data publicly.
• If a Show Page would clearly help but the user's preference is unclear, briefly ask whether they want one.
• After creating or updating a page, send the active URL and a short summary of what the page shows.