Directory layout (~/.claude/)

~/.claude/
├── projects/                  862 MB  ← main artifact store, per-project dirs
│   └── -Users-mirek-Work-...-<project-path>/
│       ├── <sessionId>.jsonl          full conversation transcript
│       ├── <sessionId>/               per-session subdirs
│       │   ├── subagents/             sub-agent JSONL + meta files
│       │   └── tool-results/          (sometimes present)
│       └── memory/                    project-scoped CLAUDE.md memory (shared)
├── file-history/               8 MB  per-session file snapshots (content-addressed)
│   └── <sessionId>/
│       └── <fileHash>@v<N>            file content before edits (undo history)
├── todos/                     72 KB  per-session to-do lists
│   └── <sessionId>-agent-<agentId>.json
├── tasks/                    700 KB  per-session task tracking
│   └── <sessionId>/
│       └── <N>.json
├── sessions/                   8 KB  running process registry (PID files)
│   └── <pid>.json                     {pid, sessionId, cwd, status, ...}
├── session-env/                0 B   per-session env dirs (appear empty, ephemeral)
│   └── <sessionId>/
├── shell-snapshots/           20 KB  zsh env snapshots (NOT per-session, global)
├── backups/                  280 KB  rolling .claude.json backups (max 5, auto-rotate)
├── history.jsonl             886 KB  global CLI input history (not per-session)
├── stats-cache.json           14 KB  global usage stats
├── settings.json               2 KB  global user settings
├── paste-cache/              344 KB  content-addressed paste blobs (not per-session)
├── cache/                    264 KB  changelog, closed-issues cache (global)
└── telemetry/                9.8 MB  telemetry data (global)

Per-conversation artifacts

The project directory name is the workspace path with / replaced by -, prefixed with -: /Users/mirek/Work/foo/bar → -Users-mirek-Work-foo-bar

Shared / global artifacts — DO NOT delete

Server-side delete

No explicit per-session delete API exists. Anthropic’s Messages API neukládá perzistentní conversation state per-request — lokální .jsonl transcript je zdrojem pravdy a CLI ho re-posílá při resumování. Nicméně:

• Anthropic má vlastní 30-day retention na server-side artefaktech (logs, training opt-out data atd.) — data nejsou okamžitě zapomenuta.
• Lokální ~/.claude/ artefakty Claude CLI také podléhají 30-day auto-cleanup mechanismu (CLI samo maže staré soubory).
• Žádný explicit per-session delete API neexistuje. Otevřený community request: https://github.com/anthropics/claude-code/issues/24126

Confirmed: claude --help has no --delete-session or similar flag. The only relevant CLI command is:

claude project purge [path]     # deletes projects/<enc-path>/ dir, tasks/, file-history/ for that path
claude project purge --all      # purges all projects
claude project purge --dry-run  # preview without deleting

project purge covers: project transcripts (all sessions), tasks, file-history, config entry in .claude.json. It does NOT delete todos or session-env (those are tiny and self-clean).

Sessions are referenced via --resume <sessionId> which simply re-opens the .jsonl file. No remote lookup.

Recommended cleanup procedure for closeConversation(projectId, sessionId, projectWorkspacePath)

Given we have (sessionId: UUID, projectWorkspacePath: String):

1. Delete conversation transcript: rm -f ~/.claude/projects/<encode(projectWorkspacePath)>/<sessionId>.jsonl

2. Delete per-session subdirectory (subagents, tool-results): rm -rf ~/.claude/projects/<encode(projectWorkspacePath)>/<sessionId>/

3. Delete file-history for session: rm -rf ~/.claude/file-history/<sessionId>/

4. Delete todos for session: rm -f ~/.claude/todos/<sessionId>-agent-*.json

5. Delete tasks for session: rm -rf ~/.claude/tasks/<sessionId>/

6. Delete session-env dir (empty but tidy): rm -rf ~/.claude/session-env/<sessionId>/

7. If closing the entire project (all conversations): use claude project purge --yes <projectWorkspacePath> — this is the official CLI command and handles the project directory atomically, including the memory/ folder and .claude.json config entry.

Path encoding: Replace every / in the absolute path with -. The encoded name starts with - (because the path starts with /). Example: /Users/mirek/Work/foo → -Users-mirek-Work-foo

Session registry (~/.claude/sessions/<pid>.json): Only present for running sessions. No cleanup needed on conversation close — the CLI removes it when the process exits.

Why we still clean up explicitly

Even though Claude CLI auto-cleans local artifacts after 30 days and Anthropic enforces 30-day retention server-side, TalkIDE still performs explicit cleanup on conversation close because:

1. Privacy-sensitive data — explicit close (user clicks “End conversation”) should remove the transcript immediately, not wait 30 days. Real incident driver: fiscal/PII data leaking into a session and the user wants it gone now.
2. DB synchronization — TalkIDE’s conversation table is the source of truth for our app, separate from Claude’s local files. Our scheduler closes stale conversation rows so the app state stays consistent regardless of CLI’s own cleanup.
3. In-memory state — ClaudeCliService keeps in-memory maps (parent refs, tool tracking) that need explicit teardown via stopProcess().

Reference for future explicit-delete API: https://github.com/anthropics/claude-code/issues/24126

Open questions / risks

• todos/ naming pattern: Files use <sessionId>-agent-<agentId>.json. The agentId can be the same as the sessionId (main agent) or a short hash (sub-agent). Glob <sessionId>-agent-*.json to catch all variants. Verify the glob doesn’t accidentally match other sessions with a shared prefix (UUIDs are unique, so prefix collision is negligible but use exact UUID match: <sessionId>-agent- not just <sessionId>).
• paste-cache/: Content-addressed, potentially shared across sessions. Do not delete per-session — it compresses naturally over time. No known cleanup mechanism.
• backups/: Contains .claude.json.backup.* files with project config entries. These auto-rotate (max 5 kept). After project purge, old backups may still reference the purged project’s config. This is benign — the config entry is just permissions/onboarding flags, not conversation data.
• file-history/ cross-session sharing: Content-addressed hashes inside session dirs could theoretically be referenced from another session if the same file version appears. In practice each session dir is independent. Safe to delete.
• No official per-session delete command: We must delete files directly. This is stable as long as Claude CLI doesn’t change its storage layout — which it has in the past. Pin CLI version in TalkIDE’s deployment to avoid surprises.

FEEDBACK

The main missing piece was documentation — Anthropic publishes no official spec for the ~/.claude/ directory layout, so everything above is derived by inspection. A claude session list or claude session delete <id> command would have made Q2 trivial. It would also have been useful to have the Claude CLI source (it’s a compiled binary) or changelog to know which dirs are guaranteed stable vs. internal implementation details.