feat(claude): support Claude Desktop import pointers and Claude Cloud migration

[elijahr]

Summary

Adds support for Claude Desktop session discovery on import and migrating from Claude Cloud exports.

• Claude Desktop companion pointer: When importing or converting to Claude format (--to claude), writes the native Claude Code JSONL session to ~/.claude/projects/ and generates the companion local_<cliSessionId>.json pointer under claude-code-sessions/<org_id>/<project_id>/ so imported sessions appear simultaneously in both Claude Desktop and Claude Code CLI.
• Cross-platform Desktop detection: Automatically resolves standard claude-code-sessions directories on macOS (~/Library/Application Support/Claude), Linux (~/.config/Claude), and Windows (%APPDATA%/Claude), with support for --claude-desktop-dir and CLAUDE_DESKTOP_CONFIG_DIR.
• Project directory matching: Dynamically maps to an existing project by matching session cwd, falls back to the active org/project directory, or initializes the default 00000000-0000-4000-8000-000000000001 pair.
• Claude Cloud migration: Adds AgentFormat.CLAUDE_CLOUD = "claude-cloud" read-only source adapter to ingest Claude.ai data export bundles (conversations.json or individual conversation JSON files).
• Format detection & conversion: Supports auto-detection and --from claude-cloud across inspect, convert, import, and catalog discovery.

Validation

• Clean linting: uv run ruff check . passed with 0 errors.
• Test suite: uv run pytest -q passed 1,543 tests, 55 skipped (100% pass rate).
• Unit tests added: 24 new tests in tests/test_claude_desktop.py and tests/test_claude_cloud.py covering desktop pointer generation, path resolution, collision handling, and cloud format ingestion.

[xhluca]

Reviewed head efab050c8d0cc00b5730961a94204ba198dd7a73 adversarially. The isolated Linux Python 3.11 suite passes (1,543 passed, 55 skipped), but three additional synthetic regression checks fail:

1. [P1] Respect an explicit target home and require opt-in for Desktop writes (claude.resolve_desktop_sessions_dir, default-path fallback; install_claude_artifact). Create an empty global ~/.config/Claude/claude-code-sessions, then import a Codex session to Claude with a separate target_home and no Desktop option. A local_<UUID>.json pointer is created in the global Desktop tree anyway. This changes an ordinary CLI import into a cross-store write outside the selected home. Do not auto-discover a global Desktop write target in this path. Require an explicit Desktop destination, and do not guess the account/organization from the newest pointer.
2. [P1] Pass the selected source UUID through the CLI loader (cli.py, line 532). With two conversations in conversations.json, claude_cloud.parse_session(path, session_id=second_uuid) succeeds, but transfer second_uuid --from claude-cloud --source-home conversations.json --to codex --home <isolated> --cwd <project> returns exit 2: discovered transcript metadata does not match the source UUID. The new optional load_session(..., session_id=...) is never used here, so it always loads the first conversation. Thread the requested ID through every transfer path and reject ambiguous file conversion rather than silently choosing the first conversation.
3. [P2] Index every conversation in an export (catalog._scan_new_portable_file, lines 2593–2596). Refreshing a directory containing that two-conversation export creates only the first conversation's row/title. claude_cloud.list_sessions is never wired into the catalog. A root passed as the export file itself is also marked unavailable by the generic directory-only refresh guard. Use a multi-session inventory/source-reference path and add title selection, exact ID selection, and file/directory-root regression tests.

The existing tests only exercise Cloud conversion of a single selected/default conversation and explicit Desktop destinations. They do not cover these public CLI/catalog behaviors. There is also no actual Claude Desktop acceptance oracle for the generated pointers.

Desktop and cloud support expand the project's current terminal-harness scope; please discuss that separately in Discussions. These concrete correctness/isolation failures need resolving independently of that product decision.

— Codex (OpenAI coding agent, GPT-6.1-sol)

[github-actions]

🟢 Contributor eligibility requirements met for @elijahr.

• 🟢 Account created: 2009-11-16; age: 6171 days (required: at least six calendar months).
• 🟢 Contributions dated on or before 2026-09-09: 5074 or more (required: at least 100).

Pull request authors must have a GitHub account at least six calendar months old and at least 100 GitHub contributions dated on or before the date one calendar month before the check.

See the contributor eligibility policy.