Skip to content

ExonUI Relay Handoff Workflow

Capture and resume structured session Relay checkpoints (.exonui/relay/) across Claude Code, Codex, Cursor, OpenCode, and Gemini CLI without losing decisions, design refs, or file state.

Grid & Relay

slug: exonui-relay319 wordssource: bundled-exonui

All skills

Use this skill before switching coding agents, before ending a long session, before context compaction, or right after opening a repo handed off from another agent.

Saving a checkpoint

  1. Collect concrete session state: · goal: the exact user objective in one sentence. · plan: ordered remaining/completed checklist items. · decisions: architectural or UI trade-offs already settled so the next agent does not relitigate them. · designRefs: Figma/Paper/Penpot URLs, node IDs, or DESIGN.md / token paths. · packs: active Grid packs (defaults to exonui.json). · filesChanged: touched files (auto-merged with git status when omitted). · openQuestions: unresolved blockers or owner decisions. · nextStep: the single highest-leverage next action. · targetAgent: optional destination (claude-code, codex, cursor, opencode, gemini-cli).
  2. Call relay_checkpoint over MCP (or run /exonui:checkpoint, or npx exonui relay checkpoint --goal "..." --next "...").
  3. Verify no raw credentials or API tokens appear in notes/decisions (redactRelaySecrets strips common token prefixes automatically, but never intentionally paste secrets).

Resuming from a checkpoint

  1. Run /exonui:resume (optionally passing a specific chk_* ID) or call relay_list followed by relay_resume.
  2. From the terminal, run npx exonui relay --to <claude|codex|cursor|opencode|gemini> [chk_id] for a copyable handoff packet box and /exonui:resume <id> command.
  3. Confirm git working tree parity against filesChanged and gitBranch before making new edits.

Claude Code `Stop` & `PreCompact` hooks

  • exonui init wires .claude/settings.json hooks by default (--no-hooks opts out); check status with npx exonui relay hooks status or npx exonui doctor.
  • exonui relay hook pre-compact preserves earlier session plan, decisions, designRefs, and openQuestions, captures transcript/git hints, and emits { "systemMessage": "..." } so /exonui:resume <id> stays top-of-context after compaction.
  • See references/packet-schema.md for field-by-field validation rules and hook guarantees.

Done when

  • A .exonui/relay/chk_*.json packet exists with accurate goal, decisions, designRefs, filesChanged, and nextStep.
  • .exonui/.gitignore keeps relay/ untracked locally.
  • The receiving session acknowledges the checkpoint via /exonui:resume or relay_resume.

Supporting references

ExonUI Relay Packet & Hook Reference

Schema (`version: 1` in `.exonui/relay/<id>.json`)

Required fields:

  • version: 1
  • id: safe identifier matching ^[A-Za-z0-9._-]+$ (e.g. chk_20261115_1045_abcd12)
  • createdAt: ISO-8601 timestamp
  • agent: originating agent (clientInfo.name in MCP, or CLI --agent)
  • goal: concise task statement
  • plan: string[]
  • decisions: string[]
  • designRefs: string[]
  • packs: string[]
  • filesChanged: string[]
  • openQuestions: string[]
  • nextStep: single concrete next action

Optional fields:

  • targetAgent: destination agent slug
  • trigger: "manual" | "stop" | "pre-compact"
  • sessionId: client session identifier (for grouping hook checkpoints)
  • gitBranch: active branch captured via git
  • notes: bounded sanitized hook/session note

Security & hygiene

  • Checkpoint reads/writes reject any ID containing path separators or traversal (..).
  • redactRelaySecrets() masks Bearer tokens, GitHub (ghp_, github_pat_), Notion (ntn_), Slack (xox*), and OpenAI/Anthropic-style sk-* keys before writing disk JSON.
  • Claude Stop hooks always check stop_hook_active === true and exit 0 immediately to avoid continuation loops, and skip duplicate writes when filesChanged + gitBranch match the latest checkpoint.