Skip to content

Source Recovery and Diagnostics

Aesop Agentic 0.4 provides Logs & Recovery in both the browser and Tauri interfaces. Every dashboard source has a Logs & Setup button. The page shows provider-specific collection results, parser counts and errors, source locations, recovery steps, and import controls. Select All Sources & Service Logs for bounded service and action log excerpts. Common credential fields are redacted; review local paths and error details before sharing logs.

Recovery Commands

aesop help-source chatgpt
aesop logs --source grok_build
aesop recover claude_desktop
aesop import claude_web ~/Downloads/claude-export.zip
claude --teleport <session-id>   # then: aesop recover claude_code
aesop parse
aesop parse --rebuild --audit-revisions
aesop verify --local-only
aesop enable-transcripts windsurf

recover collects one source and its import inbox, then parses the archive. It never resumes an agent task, changes provider credentials, or starts backups. Its results are retained in the run logs and update that source on the dashboard. An import preserves the original; ZIP members are also indexed and verified. Provider identity comes from the import source, not a shared filename such as conversations.json. ZIP extraction is staged before publication and rejects parent traversal and absolute paths.

Put downloaded exports in <repo_root>/imports/<source>/ to import them during scheduled collection. Existing installations retain their source selection; add desired IDs to [sources].enabled in the configuration. Newly initialized configurations include all registered sources. Additional Pi and Orca roots use sources.pi_session_roots and sources.orca_roots.

Coverage by Provider

“Readable” describes supplied artifacts, not a guarantee of complete account history. Unknown schemas stay opaque; malformed recognized records report errors. None of the collectors can recover data a provider never persisted or already deleted. Browser captures are always partial, even after successful sign-in.

Source ID Collection and Parsing Recovery Path and Remaining Limits
chatgpt Opaque macOS desktop files; partial web snapshots; official JSON export decoder Import the official account ZIP. Numbered conversation files are supported. Reader follows the active branch; alternative branches and attachments remain in the original export.
claude_web Official chat_messages export arrays Import Claude's account ZIP or JSON. Export availability depends on account/organization permissions. claude.ai rejects automated browsers, so aesop login claude_web cannot capture it. For claude.ai/code cloud sessions, run claude --teleport <session-id> in the session's repository; the local transcript is collected as claude_code.
claude_desktop Cowork audit JSONL is readable; Desktop Code session indexes are metadata Ordinary Desktop chats use the same official export as Web. Code transcript bodies remain under claude_code.
claude_code Saved project/session JSONL Collect on every host that ran the harness; includes local subagent records.
grok Partial signed-in web snapshots; explicit messages JSON arrays or saved text Request available data under Grok Settings → Data Controls. Other vendor export schemas are retained opaque until verified.
grok_build ~/.grok/sessions/**/{chat_history.jsonl,updates.jsonl,summary.json} Covers persisted CLI, TUI, headless, and ACP evidence. History and update streams stay separate and may overlap. grok export <id> <file.md> is another supported export route.
grok_bots Import text, message arrays, and OTLP JSON resourceLogs Cloud Bot conversations are separate from Build. Enterprise action recording/OTel is not full transcript recovery; no general full-account Bot API is claimed.
gemini_cli Persisted Gemini CLI session JSON Saved sessions only. Antigravity is now a separate source; earlier raw archives remain intact.
gemini_web Partial signed-in web snapshots Google Takeout can preserve available activity; unknown Takeout records are retained rather than misreported as complete chats.
antigravity IDE .pb files preserved opaque; brain Markdown rendered as partial evidence; CLI cache indexed as metadata Cloud/CLI session recovery uses the provider session picker. No verified protobuf decoder is installed.
windsurf Cascade .pb files preserved opaque; official transcript JSONL decodes user/planner steps and retains tool records Enable the official transcript hook. This improves future collection; it does not retroactively decode old protobuf.
trae Allowlisted editor state SQLite stores preserved opaque; explicit message-array/text imports No verified native conversation decoder or public bulk account-history API was found.
cline, roo_code VS Code task api_conversation_history.json arrays Other editor profiles can supply the same files through import.
opencode Local SQLite preserved; opencode export <id> JSON decoded Export using the provider CLI; database schema versions are not assumed interchangeable.
pi, orca Existing Pi event-tree and Orca orchestration/terminal decoders Configure extra roots and collect underlying harness transcripts independently; remote histories require collection on the remote host.

Existing Cursor, Codex, GitHub Copilot, Replit, Warp, Ollama, LM Studio, Superwhisper, and MacWhisper adapters remain available. Model providers used inside these harnesses are represented by the harness's saved history, not by an assumed provider-wide conversation API. See Source Coverage for the complete adapter overview.

Why ChatGPT Is Partial

A provider account or API key does not automatically grant access to complete consumer chat history. Opaque desktop files and partial browser snapshots do not establish that an account is empty.

Request an export through ChatGPT Settings → Data Controls → Export Data or the Privacy Portal. Download it while signed in to the requesting account, then use Import Export and Parse Archive. Self-service availability depends on the plan/workspace; managed workspaces may require administrator assistance. Exports cannot restore deleted chats. Aesop preserves all supplied files, but the reader renders the active conversation branch and does not decode every media attachment. See OpenAI's export instructions.

Windsurf Automatic Transcript Capture

aesop enable-transcripts windsurf merges a post_cascade_response_with_transcript entry into ~/.codeium/windsurf/hooks.json, preserving other hooks and saving the original as hooks.json.aesop-backup. Repeating the command is idempotent for the same installation/configuration. The hook uses the installed branded Aesop launcher when available and passes the exact config path.

The vendor writes the transcript; aesop capture-transcript windsurf accepts the hook's standard-input payload and archives only a .jsonl file confined to ~/.windsurf/transcripts. It does not execute supplied commands. The scheduled parser then renders the archived transcript. If the archive is busy, the hook reports exit 75 and the next collector pass scans the saved transcript folder. The provider caps that folder at 100 files, so prolonged failures should be resolved promptly. Restricted Mode or older builds may not run the hook.

Orca's Recovery Model

Orca distinguishes account authentication, provider session IDs, authoritative transcript paths, terminal state, and remote runtimes. Aesop follows the same separation: it collects saved evidence without assuming that a terminal session or account switch grants every provider's cloud history. Orca's private Codex runtime is already scanned alongside the ordinary Codex home. User-supplied additional roots are supported; credentials are not copied to manufacture an account-history API. See the Orca source.

Error Reference

The in-app guide and aesop logs share the packaged reference in aesop_agentic/support.py so installed wheels work without this checkout.

Result Meaning Next Step
Authentication Required Dedicated browser profile missing/expired Sign In, then Recover Saved Data.
No Conversation Links / Cached Only No fresh pages captured Refresh login or use an official export; review browser/schema changes.
Permission Denied OS or filesystem denied access Review Full Disk Access for Aesop Agentic and retry.
Not Found / Empty No allowlisted local files/messages Check saved sessions, paths, account, and host. Cloud history may still exist.
Opaque Bytes preserved; no verified decoder Supply a supported export. Rebuilding alone cannot decrypt a store.
Partial Some evidence readable, completeness limited Read source notes; supplement exports.
Parser Failure Malformed recognized record or decoder error Review artifact/line, retry after writing finishes, preserve originals.
Busy / Exit 75 Another archive operation holds the lock Wait; do not delete lock files.
SQLite Snapshot Failure Consistent read snapshot unavailable Retry while provider is idle; no unsafe main-file-only fallback.
Backup Timeout / EDEADLK Destination stalled, unavailable, or a source file is offloaded to iCloud Restore destination availability and Retry Backup. Offloaded backup files no longer need downloading; keep iCloud-hosted sources downloaded.
Interface Disconnected Local server expired/stopped Run aesop open to reconnect.

Research References

Reviewed September 21, 2026. Public schemas and UI options can change; local fixtures and live samples were used where available. Lack of a published decoder is reported as a limitation, not filled in by guessing text from binary stores.