cc-relay

Claude Code slash commands for cross-session, cross-machine handovers.

Credit

This implementation is based on the design by Howie, described in AI × Claude Code — 讓 Claude 幫你寫交班單.

The core insight from that article: instead of dragging a rotting context window across sessions, externalize the AI's working memory into a clean, structured handover that any agent can resume from.

---

The Problem

Claude Code sessions are stateless. Switching machines, opening a new session, or handing off to another agent means re-explaining everything from scratch.

The Solution

Two slash commands backed by SQLite:

Command	What it does
/handover <task-name>	Claude outputs JSON → saved to SQLite + latest-handover.md
/resume <task-name>	Reads latest-handover.md, restores context, warns on env mismatch
/handovers	Lists all sessions across all repos and tasks

The handover has two layers:

• Layer 1 (universal) — topic, decisions, blockers, next steps — works anywhere
• Layer 2 (environment) — branch, directory, test status — flagged if it doesn't match

repo-name is always auto-detected from git. task-name is required — use it to track parallel workstreams in the same repo (e.g. /handover fix-ack-bug, /handover feat-dark-mode).

Install

git clone <this-repo>
cd cc-relay
./install.sh

Installs:

• ~/.claude/commands/handover.md and resume.md — slash commands
• ~/.claude/scripts/handover-save.sh — saves JSON to SQLite + markdown
• ~/.claude/scripts/handover-load.sh — queries history from SQLite
• ~/.claude/scripts/handover-prune.sh — prunes old sessions

Quick Start

# End of session — task-name is required
/handover fix-ack-bug      # saves to ~/.claude/sessions/<repo>/fix-ack-bug/

# Start of next session — full name or prefix both work
/resume fix-ack-bug        # exact match
/resume fix               # prefix match — shows a list if multiple tasks match

# Check recent history (last 3 sessions for a task)
~/.claude/scripts/handover-load.sh fix-ack-bug 3

# Prune old sessions (keep 30 per task)
~/.claude/scripts/handover-prune.sh

# Not sure what's available? List everything
/handovers

Storage

~/.claude/
  handover.db                        ← SQLite (full history, queryable)
  sessions/
    <repo-name>/
      <task-name>/
        latest-handover.md           ← readable snapshot for /resume
        2026-04-16-1053.md           ← timestamped archives

Override the DB path:

export CLAUDE_HANDOVER_DB="$HOME/Dropbox/.claude/handover.db"

Handing Off to Someone Else

When you finish a session mid-task, you can hand the context to another person or agent.

Option 1: Send the file directly

cat ~/.claude/sessions/<repo-name>/<task-name>/latest-handover.md

The recipient places it at ~/.claude/sessions/<repo-name>/<task-name>/latest-handover.md and runs /resume <task-name> inside the same repo.

Option 2: Export as plain text (no file transfer needed)

~/.claude/scripts/handover-load.sh <task-name> 1

Copy the output and paste it into the new session as the opening message.

Option 3: Resume without this system installed

Paste the content of latest-handover.md directly into Claude and say:

"Here is a handover from my last session. Please resume from the Next Steps."

Note on Layer 2: Environment info (branch, working directory, device) is machine-specific. /resume automatically detects mismatches, warns you, and falls back to Layer 1 only — this is expected behaviour when switching machines or handing off to someone else.

Real-World Examples

Scenario 1: Save before you stop, pick up the next day

# End of day
/handover auth-refactor

# Next morning, fresh session
/resume auth-refactor

Claude instantly knows what changed, why, where it got stuck, and what to do next. No re-explaining.

---

Scenario 2: Work laptop → home machine

# Save on work laptop
/handover payment-integration

# Resume on home machine (different branch, different path)
/resume payment-integration

/resume detects the environment mismatch and warns you:

Warning: environment mismatch
  Branch:  saved=feat/payment  current=main
  Dir:     saved=/work/proj    current=/home/proj

Layer 2 info may not apply. Using Layer 1 only.

Layer 1 (task context) loads as normal. Layer 2 (environment details) is flagged but never blocks you.

---

Scenario 3: Two parallel workstreams in the same repo

# Workstream A: bug fix
/handover fix-login-bug

# Workstream B: new feature
/handover feat-dark-mode

# Switch between them by name
/resume fix-login-bug
/resume feat-dark-mode

Each task is stored independently under the same repo — they never interfere.

---

Scenario 4: Can't type the full task name

/resume fix

If one task matches the prefix, you get a confirmation prompt:

1 session matches "fix":

  1. fix-login-bug  — 2026-04-15  "Fix login race condition"

Reply with 1 to resume, or type the full name.

If multiple tasks match, you get a numbered list to pick from:

Multiple sessions match "feat":

  1. feat-auth      — 2026-04-15  "Add JWT authentication"
  2. feat-dark-mode — 2026-04-14  "Dark mode token design"

Reply with the number to resume, or type the full name.

---

Scenario 5: Forgotten what sessions exist

/handovers

Available handover sessions:
──────────────────────────────────────────
  cc-relay / auth-refactor        — 2026-04-16 22:10  "Refactor JWT middleware"
  cc-relay / fix-login-bug        — 2026-04-15 18:45  "Fix login race condition"
  dasiot-backend / feat-dark-mode — 2026-04-14 09:30  "Dark mode token design"
──────────────────────────────────────────
Resume with: /resume <task-name>   (run inside the target repo)

---

Scenario 6: Hand off to a teammate

cat ~/.claude/sessions/cc-relay/auth-refactor/latest-handover.md

Your teammate places the file at the same path on their machine and runs:

/resume auth-refactor

No system installed? Paste the file contents into Claude and say:

"Here is a handover from my last session. Please resume from the Next Steps."

---

Learn More

• Usage Guide — detailed examples and workflows
• Design Decisions — why it works this way
• Sync Guide — Dropbox, Git, and cross-account export