# Surfacing Claude Code project history out of an isolated container

**Status:** research / decided
**Date:** 2026-06-22
**Decision:** Surface **everything joinable** (option 3) via targeted rw bind-mounts, with the
one format-parsing step (`history.jsonl` merge) quarantined as a guarded, disable-able teardown.
**Run the container working dir at the same absolute path as the host** (path mirroring) — this
deletes the slug-remap hazard and keeps surfaced history host-coherent (see Hazard A).

## Problem

Isolated stacks do **not** mount host `~/.claude` wholesale (no transparent-style mirror). But we
still want a project's **history** — conversation transcripts, file-rewind backups, subagent runs,
per-project memory — to persist to the host's global Claude store so it survives throwaway
containers and shows up alongside non-containerised work. The task: identify the *exact* subpaths
to bind-mount, and the keying hazards that make a naive mount wrong.

## Layout of `~/.claude` (skimmed 2026-06-22)

Top-level dirs/files, classified by whether they hold per-project **history** vs config/cache:

| Path | Kind | Keyed by | Surface? |
|------|------|----------|----------|
| `projects/<slug>/` | History — transcripts (`<uuid>.jsonl`) + `memory/` | **project path slug** | **Yes** |
| `file-history/<uuid>/` | History — pre-edit file snapshots (`<hash>@v1/@v2`), powers rewind/undo | session UUID | **Yes** |
| `tasks/<uuid>/` | History — subagent/Task run records | session UUID | **Yes** |
| `session-env/<uuid>/` | History — `sessionstart-hook-*.sh` env captures | session UUID | **Yes** |
| `todos/<uuid>…` | History — per-session todo lists (empty on this box, session-keyed by design) | session UUID | **Yes** |
| `history.jsonl` | History — every prompt typed; each line has `"project"` + `"sessionId"` | global append, project field | **Yes, guarded** |
| `plans/*.md` | History — plan-mode artifacts, named by random slug | **no on-disk key** (project only in content) | Deferred — see Ambiguous |
| `shell-snapshots/snapshot-zsh-<ts>-<rand>.sh` | History-ish — shell env snapshots | timestamp, not session | No (can't map cleanly) |
| `sessions/<number>.json` | Session group state | numeric id (terminal/tab group) | No |
| `agents/ commands/ skills/ rules/ hooks/ plugins/` | Config | — | No |
| `cache/ .search_cache/ paste-cache/ downloads/ stats-cache.json debug/ ide/ chrome/ backups/ context-mode/ sandbox/` | Cache / runtime | — | No |
| `.credentials.json settings*.json` | Secrets / config | — | No (credentials handled by existing auth-seed layer) |

## The core hazard: two join keys

Only `projects/<slug>/` is keyed **directly** by project path. Everything else historical is keyed
by **session UUID**, generated at session start *inside* the container. The UUID→project mapping
lives in two places:

- the `.jsonl` **filenames** under `projects/<slug>/` (filename = session UUID), and
- `history.jsonl` lines (`"project"` + `"sessionId"`).

### Hazard A — the project slug differs inside the container → **solved by path mirroring**

The slug is derived from the **absolute cwd**. Evidence — both already exist on this host:

```
projects/-home-mcrowe-Programming-Personal-code-container/      ← host runs   (cwd /home/mcrowe/…)
projects/-container-mcrowe-Programming-Personal-code-container/ ← container   (cwd /container/mcrowe/…)
```

Critically, the path leak is **not just the slug** — every transcript line embeds the cwd-rooted
absolute path, and so do `file-history` references. Confirmed on this host:

```
host slug transcript:      "cwd":"/home/mcrowe/Programming/Personal/code-container"
                           "file_path":"/home/mcrowe/Programming/Personal/code-container/Dockerfile"
container slug transcript: "cwd":"/container/mcrowe/Programming/Personal/code-container"
```

If the container runs at a *different* path (`/container/mcrowe/…`), the surfaced history is
internally consistent but **host-invalid**: clickable `file_path:line` refs resolve to a
non-existent `/container/…`, rewind blobs key to paths the host can't act on, and a later host
session sees its `projects/` dir split across two slugs.

**Decision: mirror the path.** Run the container working dir at the *same* absolute path as the
host (`/home/mcrowe/Programming/Personal/code-container` inside, byte-for-byte). This:
- deletes the remap entirely — the `projects/` mount becomes plain same-path → same-path, with no
  dependency on CC's path→slug algorithm;
- keeps every recorded path host-coherent;
- makes the DooD pattern clean — container `PWD` == host `PWD`, so `-v $PWD:$PWD` works with no
  translation (satisfies §15's host-absolute-path rule directly);
- coalesces transparent + isolated runs of the same project into one history — which is the goal
  ("this project's history, regardless of how it ran").

Isolation is about **config** (skills/MCP/memory/profile), not the working-dir path; mirroring the
path leaks no host config, so the isolation guarantee is intact. Only `~/.claude` config stays
synthetic — not the project path. The current `-container-mcrowe-…` behaviour is therefore a
**change to make**, not the target state.

### Hazard B — UUID-keyed dirs have no project subfolder

`file-history/`, `tasks/`, `session-env/`, `todos/` are flat `<uuid>/` at top level. You can't
pre-create a per-project mount (UUID unknown until the session starts), so you mount the **parent
dir whole**. This is collision-free (everything is UUID-namespaced; new sessions just add dirs).
Cost: the container can *read* other projects' UUID dirs — a read-side visibility leak of file-backup
blobs, not config or secrets. Accepted.

### Hazard C — `history.jsonl` is a global append-only file

Never rw-bind it (same whole-file-rewrite race we already rejected for `.claude.json`). Surface it
by **append-merging** lines filtered on `"project"` at teardown.

## Decision rationale (why option 3, not 2)

Brittleness is **not** "more mounts." A bind-mount makes zero assumptions about dir *contents*: if a
future Claude Code release renames `tasks/`, the mount becomes an inert no-op and the new dir goes
uncaptured — **silent degradation, not container failure.** So the four UUID-keyed mounts are
effectively free in fragility terms.

The **only** genuinely brittle piece is the `history.jsonl` append-merge, because it parses an
undocumented line schema. That risk is one isolated component.

Two fragilities are **shared by options 2 and 3 equally**, so they don't favour the smaller option:
the slug-remap (depends on CC's path→slug algorithm) and the UUID-keying convention.

Net: take the full surface, quarantine the one parsing step.

## Implementation guidance

1. **Run the container at the host project path** (mirroring), then mount the project dir
   same-path → same-path — no slug remap:
   ```
   --workdir /home/mcrowe/Programming/Personal/code-container \
   -v $HOST_CLAUDE/projects/-home-mcrowe-…-code-container \
      :$CONTAINER_CLAUDE/projects/-home-mcrowe-…-code-container:rw
   ```
   Slug is identical both sides. Surfaces transcripts + per-project `memory/`. (DooD rule satisfied
   — source is a **host absolute path**, and container `PWD` == host `PWD`.)

2. **Mount the four UUID-keyed parent dirs rw** (fail-safe, collision-free):
   `file-history/`, `tasks/`, `session-env/`, `todos/`.

3. **`history.jsonl` = guarded, disable-able teardown step.** Append only lines whose `"project"`
   matches the project, wrapped so a parse failure **logs a warning and no-ops** rather than
   corrupting the host file. Ship it disabled until the format is confirmed; a CC schema change can
   then only break this one feature, not the container.

4. **Make the mount set data-driven** — a list/map in config, not inline `-v` flags — so a future CC
   layout change is a one-line manifest edit, not a code change.

5. **Add a §18 oracle assertion** — after a throwaway session, assert the host now has
   `file-history/<new-uuid>/` and `projects/<slug>/<new-uuid>.jsonl`. Silent upstream renames then
   surface as a failing test (red CI) instead of silent data loss.

## Ambiguous / out of scope

- `plans/*.md` — plan-mode artifacts carry no on-disk project key (random-slug filenames; project
  only referenced in content). Surfacing would require content inspection or mtime↔session
  correlation. Deferred.
- `shell-snapshots/` (timestamp-keyed) and `sessions/<number>.json` (terminal-group-keyed) — not
  cleanly mappable to a project. Not surfaced.

## Verification done

- `fd` skim of `~/.claude` top two levels (dirs + root files).
- Confirmed session-UUID keying of `file-history/`, `session-env/`, `tasks/` by sampling entries.
- Confirmed `projects/<slug>/<uuid>.jsonl` filename = session UUID (carries `sessionId`).
- Confirmed `history.jsonl` line schema carries `"project"` + `"sessionId"`.
- Confirmed dual-slug evidence (`-home-mcrowe-…` and `-container-mcrowe-…`) in `projects/`.
- `todos/` empty on this host but session-keyed by design (noted, not assumed populated).