Sessions and streams

An agent execution run is a session. Its real-time, append-only log is a stream.

Cards records every session on disk and streams the active output to your editor.

On-Disk Persistence

All streams are saved directly in the card repository:

• Path: streams/{streamType}/{filename}.jsonl
• Naming: {filename} follows the pattern {uuid}-{agentId}.jsonl (e.g., 01906a5a-4b03-4924-b6c7-56035d6000bd-claude.jsonl).
• Metadata: A sibling {filename}.meta.json file stores the stream's state:

  {
    "title": "Fixing type errors in database schema",
    "sessionId": "01906a5a-4b03-4924-b6c7-56035d6000bd",
    "taskContent": "Run typecheck and fix any errors under packages/db",
    "slug": "fixing-type-errors",
    "lineCount": 142,
    "createdAt": "2026-06-29T16:30:00.000Z",
    "isActive": true
  }

Live Streaming

Cards watches the streams/ directory. When an agent writes to a .jsonl file, Cards:

1. Reads the new bytes appended since the last update.
2. Streams each completed line to your editor in real time.
3. Parses the output for a slug or taskContent.
4. Updates the lineCount and metadata in the .meta.json sidecar.

If the stream is new (uncommitted), Cards opens a live tab in the editor. When the agent exits, the live tab finalizes.

Versioning and Checkpoints

To ensure your session history is preserved:

• Pre-commit: Cards automatically stages all local stream files before any commit.
• Post-commit: Cards commits the active stream and its metadata into the card repository using the message format Checkpoint stream: {sessionId}.jsonl (workspace {sha}).

Limitations

Streams are append-only. Manually editing a .jsonl file can corrupt the line count and offset cursors, causing Cards to miss new lines or desynchronize.