0xDarkMatter/summon

Summon

Copy (or move) Claude Desktop Code-tab sessions across accounts so they're visible from the account you switch to next. Full transcripts intact; no API calls; no summarisation.

When to run it

Before you switch accounts, not after. The natural workflow:

1. Notice you're approaching usage limit on the account you're currently using
2. Run summon --to <next-account> — sessions get copied (default) into the next account's dir
3. Logout from current account in Desktop → Login to the new account
4. All your mid-flight sessions appear in the new account's left-hand session picker (the sidebar on the left side of Desktop's Code tab). The Logout/Login is the natural switch you were going to do anyway.

Running summon after hitting the usage limit also works — the file moves are pure local ops, no API needed — but you'll still need to Logout/Login on the destination to see the sessions, since Desktop's session list is cached at login. Doing it proactively just means the Logout/Login is no longer "extra friction," it's the same step you'd be doing anyway.

Mental model

Each Desktop session has two halves:

| Half | Location | Account-bound? | |------|----------|----------------| | Metadata JSON | %APPDATA%/Claude/claude-code-sessions/<account>/<workspace>/local_<uuid>.json | Yes — lives under <account> | | Transcript JSONL | ~/.claude/projects/<encoded-cwd>/<cli-uuid>.jsonl | No — global, shared |

Summon copies (or with --move, relocates) the metadata wrapper into the destination account's dir. The transcript stays put — both wrappers point at the same conversation. After Logout/Login on the destination, the new entries appear in the left-hand session picker (Desktop's Code-tab sidebar).

Run

# Wrapper (after install — see below)
summon [flags]

# Or direct
python ~/.claude/skills/summon/scripts/summon.py [flags]

Default behaviour: list candidate sessions across all non-destination accounts, grouped Account → Project → Session, then prompt to copy them into the destination account. Copy semantics by default — sessions remain visible in the source account too. Last 3 days; remote-VM sessions auto-skipped.

Two natural framings of the same operation:

• Push (proactive): you're approaching usage limit on your current account. Run summon --to <next-account> while still on the current one. Pick which sessions to push. Then Logout/Login is the account switch you were going to do anyway.
• Pull (rescue): you've already switched accounts and want to bring earlier sessions over. Run summon (no --to); destination defaults to your now-current account.

Mechanically identical — the file moves are the same regardless of which framing you have in mind. Push is the recommended workflow because the Logout/Login becomes invisible.

Flags

| Flag | Default | Effect | |------|---------|--------| | --to <account> | most-recently-active account | Destination — where the sessions land. Specify when pushing to a different account; omit when pulling into your current account. UUID prefix or email substring | | --from <account> | all non-destination accounts | Restrict source to one account | | --days N | 3 | Time window | | --all | | Disable time filter | | --cwd <pattern> | | Substring match against session cwd | | --title <pattern> | | Substring match against session title | | --pick | | Interactive multi-select by number | | --move | | Move instead of copy — delete source after copying (lean cleanup) | | --dry-run | | Preview without touching files | | --list-accounts | | Show all accounts and exit | | --peek <id> | | Preview a session's last messages and exit (id prefix or full) | | --flat | | Flat list instead of grouped hierarchy | | --yes | | Skip confirmation prompt |

Auto-detect rules

• Destination: account with the most recent filesystem activity (mtime of any session JSON). This reliably tracks the active Desktop account.
• Source: by default, all accounts except destination. Use --from <account> to restrict to one.
• Workspace dir under destination: most-recently-active existing workspace. New UUID is created if the destination has no workspaces yet.

Display

Output follows the Terminal Panel Design System (panel header, body with │ rail, footer, ASCII fallback when stdout isn't UTF-8). The candidate hierarchy is Account → Project → Session, with sessions globally numbered for picker selection (3, 5, 7).

╭── 🪄 summon ──────────────────────────────────────────────── → mknv74 ───●
│
├── 4 sessions · from 1 account · last 3d
│
├── [email protected] (4)
│   ├── X:\Forge\Axiom (2)
│   │   ├──  1. train-fasttext                    30t            16h
│   │   └──  2. make-doom-for-mips                64t            16h
│   └── X:\Forma\00_workspaces\evolution7 (2)
│       ├──  3. timekeeper                        35t            16h
│       └──  4. agency-os                         17t            16h
│
│   💡  best run BEFORE switching accounts: copy sessions to the next
│       account first, then Logout/Login (the switch you were doing anyway)
│
╰── # select · a all · blank cancel ───────────────────────────────────●

Header shows → destination. Summary line shows count, source breadth, and active filter window. Body shows Account → Project → Session hierarchy with global numbering for picker selection (3,5,7). A rotating hint tile sits above the footer; the footer shows the active hotkeys.

Edge cases handled

| Case | Behaviour | |------|-----------| | Session cwd is /sessions/<vm>/mnt (remote) | Skipped — no local transcript to bridge | | Transcript JSONL missing on disk | Skipped with warning (orphan metadata) | | Same sessionId already in destination | Skipped (idempotent) | | Destination has no workspace dirs | New workspace UUID created | | Stdout is not UTF-8 (Windows cp1252) | ASCII fallback for all panel glyphs | | Stdout is not a TTY or NO_COLOR set | Plain text, no ANSI escapes |

Sidebar refresh

Desktop loads sessions into its left-hand session picker on login and doesn't watch the filesystem afterwards (verified via bundle inspection — no chokidar, no relevant fs.watch on the session dir, only direct fs.readdir calls). Summon throws a best-effort nudge at fs.watch (sentinel pings, mtime touches, rename ping-pong) but don't rely on it — assume Logout/Login is required to populate the sidebar with new sessions.

This is why summon is best run before switching accounts: the Logout/Login is what you'd do anyway. Running summon as a "rescue" after the fact still works mechanically, but the Logout/Login still has to happen.

If sessions still don't appear:

1. Try View → Reload (rarely helps; Ctrl+R only re-renders)
2. Logout → Login triggers a full filesystem rescan and always works

Wrapper install

Symlink (or copy) the wrapper into a directory on PATH:

# Linux/macOS/Git Bash
ln -s ~/.claude/skills/summon/bin/summon ~/.local/bin/summon

# Windows (PowerShell)
copy "$env:USERPROFILE\.claude\skills\summon\bin\summon.cmd" "$env:USERPROFILE\bin\summon.cmd"

Then summon --pick works directly from any shell.

Architecture reference

Full file system layout, session schemas, account binding, and the validated cross-account transfer procedure live in docs/references/claude-desktop-internals.md (claude-mods). That document is canonical; this skill is the operating manual.

Anti-patterns

• Waiting until you've already hit the limit — the file moves still work, but you've burned the chance to wrap up your current message before switching. Run summon proactively while you still have usage on the source.
• Expecting sessions to appear in the sidebar without Logout/Login — Desktop's session list is loaded on login; the kitchen-sink fs.watch nudge is best-effort and shouldn't be relied on. The Logout/Login becomes painless if you've timed summon as a push before switching.
• Running while Desktop is mid-write to a session JSON — quit Desktop first if you've literally just closed the session you want to push.
• Trying to summon remote sessions — they have no local transcript and can't be transferred.
• Hardcoding account UUIDs — use --list-accounts first, then email substring (more readable, less brittle).
• Treating this as a transfer for archived sessions — it's for mid-flight work; archived sessions belong in the source account's archive view.
• Using --move for sessions you might want to access from both accounts — copy is default precisely because multi-account workflows are the common case.