Harness Notes

Each session is one file at ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<thread-id>.jsonl. Files are grouped by date, not by project; the working directory is recorded inside the file and the resume picker filters on it. Archived sessions move to the flat ~/.codex/archived_sessions/ directory. Setting CODEX_HOME moves both directories. sqlite_home or CODEX_SQLITE_HOME only moves the SQLite index databases (state_5.sqlite, thread_history_1.sqlite).

If CODEX_HOME is set, the directory must already exist.

Each session is saved as ~/.claude/projects/<project>/<session-id>.jsonl, grouped per working directory: <project> is the directory path with every non-alphanumeric character replaced by - (names over 200 characters are truncated and given a hash suffix). CLAUDE_CONFIG_DIR moves the whole tree off ~/.claude, and CLAUDE_CODE_PROJECT_DIR_NAME (only honoured together with CLAUDE_CONFIG_DIR, v2.1.234+) lets you choose the <project> folder name yourself.

Moving a session with /cd relocates its transcript to the new directory's project folder.

In CLI 2026.10.12 each chat lives in ~/.cursor/chats/<md5 of the absolute workspace path>/<chatId>/ (store.db, meta.json, prompt_history.json), so chats are grouped per directory. A readable JSONL copy is written to ~/.cursor/projects/<workspace path with non-alphanumerics turned into dashes>/agent-transcripts/<chatId>/<chatId>.jsonl. The chats root follows CURSOR_CONFIG_DIR (or $XDG_CONFIG_HOME/cursor), and the projects root follows CURSOR_DATA_DIR.

Only the config directory override is documented; the chats/ and projects/ layout is how CLI 2026.10.12 behaves on disk.

Sessions live in the SQLite database ~/.local/share/opencode/opencode.db (follows XDG_DATA_HOME). It is shared by every project, and each session row records its project and directory. opencode debug paths db prints the path, and OPENCODE_DB overrides it, with relative values resolving under the data directory.

Each session is one file at ~/.pi/agent/sessions/--<cwd>--/<timestamp>_<session-id>.jsonl, grouped into one folder per working directory (the path with /, \ and : turned into -). Set PI_CODING_AGENT_DIR to move the whole agent directory (sessions go to <agent-dir>/sessions/), or pick a session directory with --session-dir <dir>, PI_CODING_AGENT_SESSION_DIR, or the sessionDir setting (CLI beats env beats setting). A custom session directory is flat rather than grouped per project; Pi filters it by the cwd in each file's header.

sessionDir is honoured from a project's .pi/settings.json even before project trust is granted, so Pi can find that project's sessions.

Run /session to see the current session's file path; tool shell commands also get it as PI_SESSION_FILE.

Partly

Each file is JSON Lines. Every record carries timestamp, a type (session_meta, response_item, event_msg, turn_context, compacted, token_usage_record, world_state and others) and a payload. Records can also carry ordinal and metadata. The docs give the location but don't publish a schema, so the format can change between releases. Since 0.158.0, new local threads use history_mode: "paginated". Older threads use legacy, and codex migrate-rollouts --apply converts them. For a stable interface, use the app-server thread APIs.

Cold files may be stored as .jsonl.zst when the under-development local_thread_store_compression feature is enabled. It is off by default, and Codex reads both forms.

Partly

Transcripts are JSONL: one JSON object per line for a message, tool use, or metadata entry, each tagged with a type such as user, assistant, system, or attachment. Anthropic documents the entry format as internal and says it changes between versions, so for anything durable use /export, claude -p --output-format json/stream-json, or the Agent SDK session functions rather than parsing the files.

Each message record carries the writing Claude Code version, which is the only per-record version signal.

Partly

The session itself is a SQLite database (store.db) with two tables: meta (hex-encoded JSON with the chat name, mode, model and root blob id) and blobs (content-addressed JSON and protobuf blobs forming a message tree). The JSONL mirror has one object per line: {"role","message":{"content":[...]}} plus {"type":"turn_ended","status"} lines. Neither file format is documented, so treat both as internal and liable to change.

The documented, stable machine format is the headless --output-format json|stream-json stream, not the files on disk.

Partly

SQLite. Sessions are in the session_v2 table and transcript entries in session_message, one row per entry with a type, a per-session seq and a JSON data body. The schema is internal: the docs say not to edit the database and to back it up before inspecting it with external tools. Use opencode session export or the V2 API for a stable shape.

On first start, 2.x migrates 1.x sessions in place within the same database from the old session/message/part tables into session_v2/session_message, and also imports any opencode-next.db.

JSONL: the first line is a {"type":"session","version":3,...} header, and every later line is an entry with type, id, parentId and timestamp, forming a tree. The format is publicly documented in docs/session-format.md. Older version 1 and 2 files are migrated to version 3 automatically when loaded.

New entry types still appear (for example context_edit and usage), so parsers should skip unknown types and unknown usage kind values.

The first record, session_meta, holds the thread id, cwd, CLI version, model provider, git info, base instructions and lineage fields. Later records include user and assistant messages, reasoning items, every tool call and its output (shell, custom, MCP, web search, image generation), per-turn context and settings, and turn start/complete/abort events. Compaction is recorded as compacted records with the summary and replacement history. Token usage is recorded as token_usage_record and token_count records. Attached images are stored as input_image content, either as an inline image_url (a data URL) or as an uploaded file_id.

Reasoning is stored as the model returns it, usually a summary plus encrypted content rather than raw chain of thought.

Since 0.162.0, paginated history caps persisted command output at 64 KiB and truncates oversized MCP results.

The transcript holds the full conversation: every prompt, response, tool call and tool result, plus thinking blocks, per-response token usage, compaction markers (compact_boundary with preTokens) and summaries, session titles, and other metadata. Large tool outputs and full-size MCP images spill into <session-id>/tool-results/, and pre-edit file snapshots for checkpoints live separately in ~/.claude/file-history/<session>/.

Everything is plaintext and unencrypted; a secret printed by a tool ends up in the transcript.

Since v2.1.299 the bytes of @-mentioned PDFs are no longer kept in the transcript.

Partly

store.db keeps the full model context: system prompt, user and assistant messages, tool calls and tool results, reasoning (often stored as redacted reasoning), request ids, and summary archives created by /summarize or automatic summarization. The JSONL mirror keeps user and assistant text (with any thinking text), tool calls as tool_use name and input, and turn-end status, but not tool results or the system prompt. Per-message token usage is not stored in either file.

Token counts are available to afterAgentResponse hooks at run time, not in the saved session.

Entries cover user prompts (text, files, agents, skills), assistant turns whose content is text, reasoning and tool calls (input, output content, status, errors), and shell commands. They also include synthetic and system messages, skill loads, agent/model/location switches, compaction summaries (summary, recent, reason), and idle markers ending each turn. Assistant and compaction entries carry cost and tokens (input, output, reasoning, cache.read, cache.write), and the session row keeps totals.

message entries store user, assistant, tool-result, bash-execution, custom and system messages, including text, images, thinking blocks (with opaque signatures), tool calls with arguments, and tool outputs. Assistant messages record provider, model, thinkingLevel, stop reason and usage (input, output, cacheRead, cacheWrite, totalTokens, plus a cost breakdown). Other entry types record model and thinking-level changes, compaction summaries (with tokensBefore), /tree branch summaries, context edits, non-message usage such as cache warming, labels, session names and extension data.

The system prompt and tool list are saved too: the first request writes a full system message, and later changes are saved as deltas.

Compaction and context edits never delete the original entries; the file keeps the full history.

Each subagent gets its own rollout file in the same ~/.codex/sessions/YYYY/MM/DD/ tree. Its session_meta.source records subagent.thread_spawn with parent_thread_id, depth, agent_role and agent_nickname, and the parent-child link is also kept in the thread_spawn_edges table in state_5.sqlite. Forks are new files with forked_from_id set. Auto-review (Guardian) sessions are saved in sessions/ too. Archiving or deleting a parent also archives or deletes its spawned descendants. Use /subagents to open a child thread.

Ephemeral subagents and /side chats are not written to disk.

Subagent transcripts are written beside the parent at ~/.claude/projects/<project>/<session-id>/subagents/agent-<agentId>.jsonl (with an agent-<agentId>.meta.json sidecar) and are deleted together with the parent session. Forks made with /branch or --fork-session become ordinary top-level sessions with their own IDs, and SubagentStop hooks receive agent_transcript_path pointing at the subagent file.

Compacting the main conversation does not alter subagent transcripts; subagents log their own compact_boundary records.

Partly

Subagent transcripts are written next to their parent at ~/.cursor/projects/<slug>/agent-transcripts/<parentChatId>/subagents/<subagentId>.jsonl, and the subagentStop hook receives the path as agent_transcript_path. Completed subagents keep checkpoints so they can be resumed. A /fork creates a new independent chat in the same ~/.cursor/chats/<hash>/ folder.

Subagent runs become child sessions in the same session_v2 table, with parent_id set to the calling session, and they report their results back to the parent. Forks are new sessions whose fork_session_id and fork_boundary point to the source session. opencode session list shows only top-level sessions.

Partly

Pi has no built-in subagents. /fork, /clone and --fork write a new session file in the same project folder whose header parentSession holds the source file's path, while /tree branches stay inside the original file. The example subagent extension runs each child as pi --mode json -p --no-session, so child runs aren't saved as their own sessions.

Third-party subagent extensions can save child sessions any way they like.

Prompt history for Up/Down recall and Ctrl+R search is a separate file, ~/.codex/history.jsonl. Each line is {"session_id","ts","text"} and it holds only your submitted prompts, shared across all sessions. Turn it off with [history] persistence = "none", or cap its size with history.max_bytes; when the cap is exceeded, the oldest entries are dropped.

The docs call this file 'session transcripts', but full transcripts live in ~/.codex/sessions/.

Prompt history is a separate file, ~/.claude/history.jsonl, with one line per typed prompt (text, pasted content, project path, session ID, timestamp); up-arrow recall and Ctrl+R search filter it per working directory. It isn't swept by cleanupPeriodDays (except under HIPAA configuration), but claude purge removes a project's lines and CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 stops it being written.

Large pastes in recalled prompts are stored in ~/.claude/paste-cache/, which is swept by age.

Up-arrow history is per conversation: since June 2026 it is saved in that chat's own ~/.cursor/chats/<hash>/<chatId>/prompt_history.json (up to 500 entries), separate from store.db. An older global ~/.cursor/prompt_history.json may still exist from earlier versions.

TUI prompt recall is separate from transcripts and kept in ~/.local/state/opencode/prompt-history.jsonl (last 50 entries), with frecency.jsonl next to it. The web/desktop app keeps its own prompt history in app storage.

Pi doesn't keep a separate prompt-history file. Up-arrow recall (tui.editor.cursorUp at the top of the editor, or the unbound tui.editor.historyPrevious/historyNext actions) cycles through prompts you sent in this run, and it's refilled from the user messages on the active branch when a session is opened or resumed. Your prompt history therefore comes from the session transcript.

Prompts sent with --no-session are forgotten when Pi exits.

Run codex resume to open a picker, codex resume --last to continue the most recent session in the current directory, or codex resume <SESSION_ID|name> for a specific one. Add --all to search outside the current directory and --include-non-interactive to include codex exec runs. Inside the TUI, use /resume. For scripts, use codex exec resume --last "<prompt>" or codex exec resume <SESSION_ID> "<prompt>". codex fork, codex exec fork or /fork copies a session into a new one.

When the saved working directory differs from the current one, Codex asks which to use. Set tui.resume_cwd = "current" or "session" to skip the question; -C overrides it.

claude --continue (-c) reopens the most recent session in the current directory, claude --resume (-r) opens a picker, and claude --resume <session-id|name|/abs/path/to/file.jsonl> resumes a specific one; inside a session use /resume [session]. Add --fork-session (or run /branch in-session) to continue in a copy with a new session ID, and claude -p --resume <id> "prompt" continues one non-interactively.

Flags such as --mcp-config, --settings, --plugin-dir and --add-dir are not restored and must be passed again.

Resuming a background session that is still running attaches to it instead (v2.1.285+).

Run agent resume or agent --continue (an alias for --resume=-1) to reopen the latest chat, agent --resume <chatId> to open a specific one, or /resume (Ctrl+Y) inside a session. Resume also works with -p for headless follow-ups, and /fork branches the current chat into a new session.

Run opencode --continue (-c) for the last session or opencode --session <id> (-s), which creates the session if the ID does not exist. opencode run and opencode mini take the same flags plus --fork. In the TUI, /sessions (aliases /resume, /continue) picks a session and /fork branches the current one.

Run pi --continue (-c) to reopen the most recent session for the current folder, pi --resume (-r) for a picker, or pi --session <path|id> to open a file path, exact ID or partial ID. Inside Pi, /resume switches sessions and /import <path> imports and resumes a JSONL file. pi --fork <path|id> starts a new session copied from an existing one, and --session-id <id> opens that ID in this project or creates it.

If --session matches a session from another project, Pi offers to fork it into the current folder instead of opening it.

codex resume and /resume open a paginated picker of sessions in the current directory. Type to filter the loaded rows, press Tab to switch the filter to all directories or to archived sessions, and press Ctrl+E to preview a transcript. Give a session a name with /rename so codex resume <name> can find it. codex agents (or /agents) lists chats on the shared background server. Programs can call app-server thread/list, which supports searchTerm, cwd, archived and source filters.

Session names are kept in ~/.codex/session_index.jsonl, an append-only file where the latest entry wins.

claude --resume or /resume opens a session picker for the current worktree; type to search, Space to preview, Ctrl+R to rename, Ctrl+B to filter by branch, Ctrl+W for all worktrees and Ctrl+A for every project on the machine. Name sessions with claude -n <name> or /rename so claude --resume <name> finds them, and claude --from-pr <number|url> lists sessions linked to a pull request.

Sessions created with claude -p, the Agent SDK, or starting with /loop are hidden from the picker and --continue, but still resume by ID.

agent ls (or agent --resume with no id, or /resume) opens a picker that lists All chats across workspaces by default, with Created and Last updated columns. Left/Right switches to This workspace. There is no full-text search over CLI chats; /copy-conversation-id copies the current chat id.

Use /sessions in the TUI, or opencode session list for top-level sessions in the current project, newest first. -n limits the count (default 100) and --format json gives machine output. To search, query the database read-only, for example sqlite3 "$(opencode debug paths db)".

pi --resume or /resume opens a picker for the current folder that can switch to all folders. You can type to search, and use Ctrl+P to show paths, Ctrl+S to change sort order, Ctrl+N to show only named sessions, Ctrl+R to rename and Ctrl+D to delete. Name sessions with /name or --name so they're easier to spot, and run /session to see the current file, ID, message count, tokens and cost.

Session files are plain JSONL, so grep across ~/.pi/agent/sessions also works.

Partly

/export in the TUI exports the whole conversation as Markdown, either to the clipboard or to a file (/export session.md). /copy (or Ctrl+O) copies only the latest response. There is no HTML export and no share link for local sessions. To get JSON, copy the rollout .jsonl file or read the thread through the app-server API.

Wait for the current turn to finish before running /export.

Partly

/export copies the current conversation to the clipboard or saves it as a plain-text file (/export <filename> writes directly). There is no built-in Markdown, HTML or share link for local CLI sessions; for JSON use claude -p --output-format json or read the .jsonl file, and only cloud sessions on claude.ai/code can be shared by link with Private/Team/Public visibility.

/feedback, /bug and /share send a transcript to Anthropic as a report, not as a shareable link.

Partly

The CLI has no export or share command. You can copy the JSONL file under ~/.cursor/projects/<slug>/agent-transcripts/<chatId>/ yourself. Share links (cursor.com/s/...) are created from the Cursor editor's chat header and need a Teams or Enterprise plan.

/copy copies only a previous user message, not the conversation.

Partly

opencode session export [id] prints the session as JSON (--sanitize redacts it), and opencode session import <file|url> restores it. In the TUI, /export saves a transcript and /copy copies it to the clipboard. Share links are not available in 2.x: /share reports sharing as unavailable.

Export and import moved from top-level opencode export/opencode import in 1.x to the opencode session subcommands.

/export [path] writes the session as HTML, or as JSONL if the path ends in .jsonl (the JSONL export holds only the current branch). pi --export <session.jsonl> [output.html] turns a session file into HTML without starting a session. /share uploads the session and gives you a link. If you're signed in to Radius it creates an artifact your Radius organization can see; otherwise it creates a private GitHub gist through gh and gives you a https://pi.dev/session/#<gist-id> viewer link (change the base with PI_SHARE_VIEWER_URL).

Exports and shares can contain prompts, command output, file contents and any credentials that appeared in the conversation. Review them before sharing.

The supported interface is codex app-server (JSON-RPC). thread/list, thread/read, thread/turns/list and thread/items/list read stored threads without resuming them; thread/resume, thread/fork, thread/archive and thread/delete manage them. codex exec --json streams JSONL events (thread.started with thread_id, item.*, turn.completed) for a live run. The TypeScript and Python SDKs can resume a thread by id, for example codex.resumeThread(threadId). You can also parse the rollout JSONL files directly, but they have no published schema.

codex app-server generate-json-schema and generate-ts (both experimental) emit the protocol types.

The Agent SDK exposes listSessions(), getSessionMessages(), getSessionInfo(), renameSession(), tagSession() and forkSession() in TypeScript (list_sessions(), get_session_messages() and friends in Python), plus resume/forkSession options and a sessionStore adapter for mirroring transcripts to your own storage. From the CLI, claude -p --output-format json or stream-json returns the result, session ID, usage and cost, and hooks and status line commands receive the live transcript_path.

Headless runs (agent -p --output-format json or stream-json) emit a documented NDJSON stream with session_id, messages and tool call start/completion events, and you can pass that id back with --resume. agent create-chat returns a new chat id, hooks receive transcript_path (and CURSOR_TRANSCRIPT_PATH), and agent acp exposes sessions over the Agent Client Protocol, including session/load.

thinking events are left out of print-mode output.

Every client talks to a local background server whose V2 HTTP API includes session.list, session.get, session.message.list (GET /api/session/{sessionID}/message), session.log and experimental.session.export. Use it through the @opencode/client package or opencode api. opencode run --format json emits JSON events. The V1 server API and SDK are not compatible with 2.x.

The SDK (@earendil-works/pi-coding-agent) exports SessionManager with create, open, continueRecent, list, listAll, forkFrom and inMemory, plus tree and context helpers. pi --mode json -p streams a session header and then session events as JSONL on stdout. pi --mode rpc offers get_messages, get_entries (every entry, including abandoned branches and pre-compaction history, with a since cursor), get_tree, get_state (session ID and file), get_session_stats, export_html, switch_session and fork.

You can also parse the JSONL files directly; session-format.md includes a parsing example.

Partly

Session files are kept until you remove them; Codex never deletes them by age. codex archive <SESSION> or /archive moves a session to ~/.codex/archived_sessions and out of the picker, and codex unarchive restores it. codex delete <SESSION> or /delete permanently removes the transcript, its spawned subagent sessions and their metadata; --force skips the prompt but only accepts a UUID. Only the separate prompt history file is size-capped, via history.max_bytes.

If you delete files by hand, the SQLite index in state_5.sqlite can keep stale entries until the next listing scan repairs it. codex delete keeps both in sync.

A background sweep deletes transcripts, subagent transcripts and tool-result sidecars older than cleanupPeriodDays (default 30, minimum 1; 0 is rejected, so use a large value like 3650 to keep them long). Desktop and Cowork transcripts are kept at any age unless you set desktopSessionCleanupPeriodDays. Delete sooner with claude purge [path] (--dry-run, --yes, --all; formerly claude project purge) or by removing files under ~/.claude/projects/.

claude rm <id> on a background session leaves its transcript on disk.

The sweep is skipped with claude -p --bare and pauses if settings can't be parsed.

Partly

Local CLI chats have no expiry and are kept until you delete them. In the agent ls / /resume picker, press Backspace or Delete on a chat and confirm to permanently remove its ~/.cursor/chats/.../<chatId> folder. You can also delete that folder, and the matching agent-transcripts/<chatId> folder, by hand.

Deleting from the picker removes the chat folder. The JSONL copy under ~/.cursor/projects is a separate file, so check it too.

Partly

Sessions are kept indefinitely, and opencode uninstall explicitly keeps session data. Delete a session and its child sessions with opencode session delete <sessionID> or the API's session.remove. Only spilled tool and shell output files are aged out, after 7 days.

Pi keeps sessions until you delete them; there's no automatic expiry or retention setting. Delete a session by removing its .jsonl file under ~/.pi/agent/sessions/, or select it in /resume and press Ctrl+D and confirm. Pi uses the trash CLI when it's installed, so the file can be recovered.

You can't delete the session that's currently open from the picker.

A session file is only created once the session has a user or assistant message, so opening and closing Pi without chatting leaves no file.

Partly

For non-interactive runs, codex exec --ephemeral "<prompt>" writes no session file and no state-DB row. App-server clients can pass ephemeral: true to thread/start or thread/fork, and /side opens an ephemeral side chat. Interactive codex has no ephemeral flag or config setting. history.persistence = "none" only stops prompt history (history.jsonl); session transcripts are still written.

The config reference describes history.persistence as controlling whether session transcripts are saved to history.jsonl. In practice it only gates prompt history, not the rollout files under sessions/.

Set CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 to stop writing transcripts and prompt history in any mode; such sessions can't be resumed. For a single non-interactive run use claude -p --no-session-persistence, and in the TypeScript Agent SDK set persistSession: false.

The Python Agent SDK has no persistSession option; use the environment variable.

CLAUDE_CODE_TRANSCRIPT_LOCAL_GC=1 instead trims long -p/SDK transcripts past 5 MB after each compaction.

Not supported

There is no flag, setting or environment variable to run without saving the session; every interactive and -p run creates a chat under ~/.cursor/chats. To get a throwaway session, point CURSOR_CONFIG_DIR and CURSOR_DATA_DIR at a temporary directory (you will need credentials there too) or delete the chat afterwards.

Partly

There is no documented no-save switch. OPENCODE_DB=:memory: (accepted by opencode debug paths) keeps the database in memory, so nothing persists after the server stops. With the shared background service, it has to be set for a --standalone run or for the service itself.

Start Pi with --no-session to keep the session in memory only; nothing is written, and the session can't be resumed after Pi exits. SDK hosts get the same thing with SessionManager.inMemory().

There's no setting that turns persistence off for every run; pass the flag (or a shell alias) each time.

--no-session can't be combined with --fork.

Partly

Local sessions are not uploaded. They stay under CODEX_HOME, which the CLI, the IDE extension and the ChatGPT desktop app's Codex view all share, so /app can continue the same saved chat in the desktop app. codex remote-control lets another device drive your local background server, but transcripts stay on your machine. Codex Cloud tasks (codex cloud) are separate cloud chats. The only upload path is /feedback: if you choose to include logs, it attaches the session's rollout files.

ChatGPT Work local-thread sync is a separate ChatGPT Work feature; Codex keeps its own history.

Local CLI transcripts stay on your machine by default and --resume doesn't list cloud sessions. While Remote Control is connected, the session transcript is also stored on Anthropic servers to sync with claude.ai and the Claude app; cloud sessions on claude.ai/code are stored by Anthropic and can be pulled into a terminal copy with claude --teleport or /teleport. Transcripts are uploaded only when you send /feedback, /bug or /share, or answer Yes to the optional session-transcript survey (disable with CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1).

Turn Remote Control auto-connect off with remoteControlAtStartup: false or /config.

Teleport is one-way: work continued in the terminal isn't pushed back to the cloud session.

Partly

CLI chats are stored only on your machine and are not synced to the Cursor editor, the web or other devices. Your prompts and context still go to Cursor's servers for each model request, and Privacy Mode controls whether that data can be retained or used for training. Prefixing a message with & hands the conversation off to a Cloud Agent, which you can then open at cursor.com/agents.

The resume picker can also list your cloud agents next to local chats.

Partly

Transcripts stay in the local database owned by your background server, and 2.x has no session sharing yet. The share config key (manual/auto/disabled) is accepted but has no effect. Other devices reach sessions only by connecting to your server, for example with opencode pair links or --server <url>; nothing is uploaded to a cloud service.

Sessions stay on local disk and aren't synced to any cloud or other device. They only leave your machine when you run /share (a Radius artifact visible to your organization, or a private GitHub gist) or choose to attach the transcript to a /bug report, which uploads to radius.pi.dev unless you export the report as a zip instead. To sync across machines yourself, point --session-dir, PI_CODING_AGENT_SESSION_DIR or sessionDir at a synced folder.

PI_OFFLINE turns off automatic network activity, but /share and /bug are things you run yourself.