claude-recoverer

ClaudeRecoverer is an experimental, unofficial Node.js CLI and self-contained Agent Skill. It combines an official Claude account export with files and Project metadata that remain available to an authorized session, validates the result, and writes a portable recovery ZIP. A separate workflow backs up and imports local Claude Desktop Cowork data without account binding or cloud sync.

[!IMPORTANT] ClaudeRecoverer is not affiliated with Anthropic and is not an authentication-bypass tool. Use it only with accounts, exports, browser sessions, and local data that you own or are authorized to recover. A recovery package contains private conversations and files.

Recommended setup

Use the bundled Agent Skill with Codex. The Skill follows the OpenAI Skill format and guides the Agent through source validation, local credential entry, package construction, validation, and optional Cowork import. A frontier model is not required: the CLI performs the deterministic work and the Agent mainly selects and sequences supported commands.

• Recommended: Codex + the claude-recoverer Skill.
• Advanced: run the CLI directly from a source checkout.
• Node.js 20 or newer is required.
• Account rescue requires an official Claude full-account export ZIP or extracted directory.
• Cowork backup/import requires local Claude Desktop Cowork data, but no Claude login or Cookie.

The public distribution target is currently the self-contained Skill. The CLI is not published to npm yet.

What it recovers

Packages may include prompts, replies, exported thinking/tool events, uploads, outputs, Project relationships and context, hashes, completeness reports, and import provenance. They never contain Cookie plaintext, browser databases, OAuth state, or executable recovery code.

Authentication and platform support

ClaudeRecoverer supports two practical paths for online enrichment:

1. Cookie Input — recommended and cross-platform. The CLI opens a page bound to 127.0.0.1. Paste Cookie data and optionally select a detected User-Agent. The value stays in the local process; the Agent does not read it and the recovery package does not store it.
2. Automatic browser Profile access — currently macOS only. Chrome, Edge, Brave, and Chromium Profiles can be discovered and verified on macOS. Windows and Linux users should use Cookie Input for now.

claude-recoverer auth cookie-input --json
claude-recoverer auth discover --json
claude-recoverer auth user-agent discover --json

Browser discovery lists capabilities only. The user must explicitly select one Provider before ClaudeRecoverer accesses an account.

Getting Cookie data safely

Option A: Cookie-Editor

Cookie-Editor is the recommended multi-format export tool. Official downloads:

• Chrome / Chromium browsers
• Firefox
• Microsoft Edge
• Opera
• Safari
• GitHub source and releases

1. Sign in to https://claude.ai/ in your browser.
2. Open Cookie-Editor for the Claude tab.
3. Export Header String, JSON, or Netscape format.
4. Paste the result only into ClaudeRecoverer's local Cookie Input page.
5. Close the page after verification. Sign out of Claude when the rescue is complete if you want to invalidate the session.

ClaudeRecoverer automatically recognizes supported Header String, Cookies Editor, Netscape, and scoped JSON formats.

Option B: browser Developer Tools

1. Open https://claude.ai/ and the browser Developer Tools.
2. Select Network, reload the page, and choose a same-origin request such as new or an /api/... request.
3. Under Request Headers, copy only the value of the Cookie header.
4. Paste it into ClaudeRecoverer's local Cookie Input page. Do not paste it into chat, a command argument, an environment variable, an Issue, or a screenshot.

If documenting the process, crop or redact every Cookie value, session identifier, signed URL, email address, and Organization ID before sharing the screenshot.

Account rescue with the Skill

A normal guided rescue requires only a few decisions:

1. Give the Agent the official account-export ZIP.
2. After preflight, choose Cookie Input or one discovered macOS browser Profile.
3. If several Organizations remain genuinely ambiguous, select the matching one.
4. Wait while the Agent builds, validates, packs, and independently validates a uniquely named recovery ZIP.

Example user request:

Use this official Claude export to build a complete account recovery package.
Save it in the current directory. Report every unavailable file and do not import
anything into Cowork yet.

Direct CLI outline:

claude-recoverer doctor \
  --workflow account \
  --export-zip /absolute/path/to/official-export.zip \
  --json

claude-recoverer account prepare \
  --auth-provider cookie-file \
  --cookie-file /absolute/path/from-cookie-input.json \
  --export-zip /absolute/path/to/official-export.zip \
  --destination-parent /absolute/existing/directory \
  --projects all \
  --conversations all \
  --membership-policy strict

claude-recoverer account validate --package /absolute/path/to/package
claude-recoverer account pack \
  --bundle-dir /absolute/path/to/package \
  --zip-out /absolute/path/to/package.zip
claude-recoverer account validate --package /absolute/path/to/package.zip

Use claude-recoverer account --help for selection and advanced options. Do not pre-create or delete the final package directory; use a new destination or --destination-parent.

Cowork backup and import

Local Cowork backup needs no Claude account, Organization ID, browser, or Cookie:

claude-recoverer cowork inventory
claude-recoverer cowork export \
  --zip-out /absolute/path/to/cowork-backup.zip \
  --projects all \
  --conversations all \
  --project-files safe
claude-recoverer cowork validate --package /absolute/path/to/cowork-backup.zip

--project-files safe excludes common dependency, source-control, environment, credential-like, private-key, symlink, and oversized files.

Import is a separate authorization. Quit Claude Desktop first and preserve a backup of the current Cowork state:

claude-recoverer account import \
  --package /absolute/path/to/account-recovery.zip \
  --projects all \
  --conversations confirmed-standalone \
  --project-root /absolute/path/to/project-folders

Do not import export-only or unclassified conversations as standalone by default. Repeated imports should be verified for idempotence.

Reading the result

• ok: true: package structure and referenced hashes validate.
• complete: true: every item in the selected recovery scope is available.
• activeComplete: completeness of currently confirmed Project and standalone content.
• originalOutputsComplete: every historical output is independently available as its original binary.
• recoveryOutputsComplete: every output has a usable downloaded or explicitly reconstructed asset.
• projectContextsComplete: selected Project Description, Instructions, Memory, documents, and knowledge files are complete.

These fields describe different boundaries. A useful, valid package may have ok: true and complete: false.

Current limitations

• Claude may delete historical outputs, expire them, or replace same-path historical versions. Those resources commonly return HTTP 404 and cannot be downloaded by this tool.
• Several exported UUIDs may refer to one conversation/path. ClaudeRecoverer stores one physical binary and reports shared-path / identity-ambiguous provenance rather than claiming independent versions.
• There is no supported automatic workflow for reconstructing expired files from exported Python, JavaScript, shell, or tool-execution traces. ClaudeRecoverer never executes those traces automatically.
• Cowork transcripts are currently compiled linearly; original conversation branch topology is not guaranteed.
• To bound traffic and reduce unnecessary repeated access to Claude, each output-file download attempt currently has a 10-second budget. A large file that cannot finish within that window on the current connection may be reported as a transient failure. Try again on a stable connection and compare independently validated packages.
• complete is therefore not a universal measure of rescue quality. Historical 404s, shared paths, and intentionally unsupported reconstruction can keep it false. A stable repeated result—same successful task count, same hashes, and the same explicit 404 set—is a stronger practical completion signal.
• Real tests found that simply increasing the overall request budget on a low-bandwidth connection did not reliably improve the full-package success rate, so the conservative limit remains for now.
• Automatic browser Profile authentication is currently macOS-only. Cookie Input is the supported cross-platform path.
• Import currently targets Claude Desktop Cowork, not other Cowork implementations.

Privacy and safety

• Keep exports, recovery packages, Cowork data, and Cookie material private.
• Never commit real data as fixtures or attach it to a public Issue.
• Cookie plaintext must remain inside the local authentication page or a user-controlled restricted file.
• Signed URLs and authentication headers are removed from reports.
• Validate before import; quit Claude Desktop and back up Cowork before mutation.
• Use --force only for an exact destination that the user explicitly approves replacing.

Skill and CLI maintenance

The Skill lives in skills/claude-recoverer/ and includes its own verified runtime.

npm run check
npm test
npm run build:skill
npm run verify:skill
npm run release:skill

Issues, sanitized reproducible reports, platform validation, and import adapters are welcome. Include the operating system, Node.js version, workflow, redacted command shape, package version, and exact safe error code. See CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md.

License

ClaudeRecoverer is released under the MIT License.

ClaudeRecoverer preserves only official exports, local Cowork state, and resources still available to the user's authorized session.