claude-desktop-sessions

Files (3)

• SKILL.md
• migrate.py · scripts/
• test_migrate.py · scripts/

SKILL.md (first lines)

# claude-desktop-sessions

Surface terminal-CLI Claude Code sessions in the **Claude Desktop** app's **Code** tab, and hand a
running session off to Desktop (which also makes it reachable from the phone through Remote Control).

## Why the sessions are missing (the root cause)

Desktop and the CLI keep **separate session lists** but **share one transcript store**. The official
docs say it plainly: coming from the CLI, "each maintains separate session history" while sharing
configuration and `CLAUDE.md`. So a session you started in the terminal is never listed by Desktop,
even though Desktop can read its transcript.

Two facts, both verified against Desktop 1.24012.0 (bundled Claude Code 2.1.215) on Linux:

1. **Shared transcript store.** Both write `~/.claude/projects/<encoded-cwd>/<cliSessionId>.jsonl`.
   Desktop's bundle joins `claudeConfigDir` (default `~/.claude`) with `projects` and names files
   `${cliSessionId}.jsonl` — identical to the CLI. So the transcript never needs to move.
2. **Separate sidebar registry.** Desktop's Code sidebar is driven by one small JSON file per
   session at `~/.config/Claude/claude-code-sessions/<accountId>/<workspaceId>/local_<uuid>.json`.
   That file is the only thing the CLI does not create — this skill creates it.

The obvious built-in path, the in-session `/desktop` command, is **compiled off in current builds**:
its gate function returns a hard `false`, so the command is hidden for everyone regardless of account.
Writing the registry file is the working alternative.

The encoded-cwd directory name is the cwd with every non-`[a-zA-Z0-9]` character replaced by `-`
(e.g. `/media/user/New Volume1/projects/2026.04.29_agent_rules` →
`-media-user-New-Volume1-projects-2026-04-29-agent-rules`). The tool reads the real cwd from inside
the transcript rather than trying to reverse this lossy encoding.

## The tool

`scripts/migrate.py` — dry-run by default, writes nothing until told to. It never touches a
transcript and only ever *adds* registry files, so undo is `rm` on the files it names.

```bash
MIG="$(dirname "$0")/scripts/migrate.py"    # or the skill's scripts/migrate.py

python3 migrate.py --list                    # numbered table of registerable sessions (writes nothing)
python3 migrate.py --pick 1,3,5 --apply      # register those rows from the --list numbering
python3 migrate.py --pick 1-4,7 --apply      # ranges work too
python3 migrate.py --session <cliSessionId> --title "My label" --apply   # one exact session, custom title
python3 migrate.py --apply                   # register ALL registerable sessions (use --max-mb to cap size)
```

`--list` numbering is by conversation start time, newest first, and is stable for a following
`--pick` because it sorts on the transcript's immutable first timestamp, not on the file mtime.

### What it refuses to do, and why

- **Deleted sessions stay deleted.** Deleting a session in Desktop writes a `deleted_<id>`
  tombstone; the tool skips tombstoned ids so a batch run never resurrects them. (Deleting a session
  in Desktop does *not* delete its transcript — verified.)
- **`/tmp` scratch sessions are filtered out.** A cwd of `/tmp` or under it (where throwaway sessions
  accumulate — over a thousand on this machine) is skipped.
- **Already-registered and orphaned sessions are skipped** — no duplicate sidebar rows, and a session
  whose cwd no longer exists is left out.
- **A live session is flagged, not silently registered.** If a session is running in a CLI right now
  (`--list`/output marks it `[RUNNING NOW]` and warns on stderr), you must **exit that CLI before
  opening the session in Desktop**. Two processes appending to one transcript corrupts it — the worst
  outcome this tool can cause.

## Handing a running session to Desktop (the safe order)

1. Register it: `python3 migrate.py --session <id> --title "…" --apply`.
2. **Fully quit and reopen Desktop** — it reads the registry directory only at startup.
3. **Exit the CLI** running that session; confirm no `claude` process is still on it.
4. Open the session in Desktop's Code tab. Its history loads from the shared transcript.

Order matters: the CLI must exit before the session is opened in Desktop (step 3 before step 4).

## Remote Control (reaching it from the phone)

Registering a session does not by itself enable Remote Control. For a session to appear on the phone:

- Set `remoteControlAtStartup: true` in `~/.claude/settings.json` (or run `/config` →
  *Enable Remote Control for all sessions*), **and**
- In the Desktop app, enable **Settings → Claude Code → Enable remote control by default**. The
  settings-file flag alone did not make Desktop-hosted sessions connect; the Desktop toggle was
  required. Once both are on, the session shows in the Claude mobile app's Code list.

Remote Control is disabled when `ANTHROPIC_BASE_URL` points anywhere other than `api.anthropic.com`,
so leave that unset.

## Does the session archiver cover Desktop sessions?

Yes, automatically, and for the same reason the migration works: the archiver
(`claude-session-archiver` / worknroll `daily archive`) globs `~/.claude/projects/*/*.jsonl`, which
is exactly where Desktop-hosted Code sessions write. No change is needed for Desktop coverage —
verified that the glob matches a live Desktop session's transcript and that the daily
`wd-archive.timer` picks it up. (Cowork VM sessions are a separate store and out of scope here.)

## Caveats

- **Undocumented schema.** The registry record shape was read off a sample Desktop itself produced. A
  Desktop upgrade may change it; if a migrated session stops opening, re-run after re-reading one
  freshly-created record.
- **Restart required.** New records appear only after Desktop restarts.
- **Huge transcripts are slow to resume.** Desktop opens a session by spawning `claude --resume`;
  a multi-hundred-MB transcript can be slow or memory-heavy. Use `--max-mb` to cap a batch. A 95 MB
  session was verified to open fine; the largest here are ~200 MB.
- **`model`/`effort` are intentionally omitted** from the record, so a migrated session keeps
  whatever model the CLI would pick rather than being silently re-pointed.

## Tests

`scripts/test_migrate.py` — 18 checks, run `python3 scripts/test_migrate.py`. Two are regressions
that lock out real bugs found while building this: a `/tmp` filter that let a bare `/tmp` cwd through,
and a UTC-vs-local timestamp skew. The timestamp test runs under a non-UTC timezone on purpose,
because the bug is invisible under `TZ=UTC`.

From jajupmochi/agent-harness, MIT.

More from jajupmochi/agent-harness