cc-session-io weekly downloads statistics

cc-session-io

Read, write, and create Claude Code session files.

Can create new session history files or read/write existing ones that will work with /resume in Claude Code. Useful for importing conversation history from another coding agent to continue it with claude.

No runtime dependencies. Not affiliated or supported by Anthropic, the makers of Claude Code.

Scope

Reads and writes user and assistant message records, with text, thinking, tool_use, tool_result and image content blocks, and attachment records — Claude Code's own injected context, such as an @file expansion. importMessages repairs tool_use/tool_result pairing on the way in. Sessions written this way resume in Claude Code.

Preserves every other record type Claude Code writes (queue-operation, last-prompt, summaries, and anything added by a future release) through UnknownRecord, so a read-modify-write leaves them untouched. Writing one means dangerousAppendRecord(), which appends whatever you hand it — the typed helpers only cover messages and attachments, because the other record types share almost none of their fields and synthesizing those would produce records Claude Code never writes.

Does not handle subagent transcripts: isSidechain is always written false, and Claude Code keeps sub-agent conversations in a separate subagents/ directory that this library neither creates nor manages. See also the Bun/Node hash mismatch for project paths over 200 characters.

Install

Requires Node >= 20.

Simple CLI Demo

Options: • -p - Project path (required) • -s - Session ID (required for add/read)

Quick Start

Create a new session

Append to an existing session

API

createSession(opts): Session

Creates a new session. Generates a UUID session ID and resolves the JSONL path.

| Option | Type | Default | Description |

| projectPath | string | *required* | Absolute path to the project. Determines where the JSONL file is written. | | claudeDir | string? | ~/.claude | Override the Claude config directory. | | cwd | string? | projectPath | Working directory written into records. | | gitBranch | string? | "HEAD" | Git branch name written into records. | | version | string? | "2.1.83" | Claude Code version to claim. | | model | string? | "claude-sonnet-4-6" | Default model for assistant messages. |

openSession(opts): Session

Opens an existing session by ID for reading or appending.

| Option | Type | Description |

| sessionId | string | UUID of the session. | | projectPath | string | Absolute path to the project. | | claudeDir | string? | Override the Claude config directory. |

readSession(jsonlPath, projectPath?): Session

Reads a session directly from a JSONL file path.

Session

Properties

| Property | Type | Description |

| sessionId | string | UUID of the session. | | projectPath | string | Project path. | | jsonlPath | string | Absolute path to the JSONL file. | | records | JsonlRecord[] | All JSONL records (including non-message types). | | messages | (UserRecord \| AssistantRecord)[] | Only user and assistant records. | | attachments | AttachmentRecord[] | Only attachment records. |

session.addUserMessage(content): string

Adds a user message. content is either a string or an array of user content blocks (text, image, tool_result), which are written unchanged. Throws on an empty array, which Anthropic rejects. Returns the record's UUID.

session.dangerousAppendRecord(record, opts?): void

Appends a record verbatim. The escape hatch for record types this library does not model, and for carrying records from one session into another — with one exception: use addAttachment for attachments.

Dangerous because nothing is synthesized or validated beyond sessionId and the parent link — the shape is whatever you pass, and Claude Code will read it back. sessionId is overwritten with this session's, since a record claiming another session is never what a caller wants. The record is appended verbatim and does not advance the chain, so the next message parents to whatever came before it. That is right for chain-external records like queue-operation, but wrong for attachments — Claude Code threads those through the chain, so carry them with addAttachment instead.

parentUuid is the one thing checked: a dangling parent makes Claude Code resume with empty context and answer confidently from nothing, and it does not announce itself, so it throws instead.

session.addAttachment(attachment, opts?): string

Adds an attachment record — Claude Code's injected context, written as its own record rather than as part of a message. The payload shape varies by attachment.type; only file and edited_text_file carry content a consumer cannot regenerate, and Claude Code rewrites the rest (skill_listing, task_reminder, agent_listing_delta, …) every turn.

Attachments are links in the uuid chain, not leaves hanging off it — the record that follows one parents to the attachment — so this advances the chain exactly as the message methods do. parentUuid defaults to whatever the session would currently chain from; pass it explicitly when carrying a record over from another session, where the message it belongs to has been given a new UUID.

Because they sit *in* the chain, inserting one between existing records would mean re-parenting the record that follows, which this method does not do — it appends. To place attachments within a conversation, pass them to importMessages instead:

afterIndex indexes the array you passed. repairToolPairing runs inside the import and can insert or drop messages, so positions are mapped through the exported repairWithOrigin(). An attachment whose message the repair dropped is not emitted, nor is one with an out-of-range index (which logs a warning), so check session.attachments when it matters.

session.addAssistantMessage(content, opts?): string…

Description from the npm listing.