mcpField
C
ce-session-extract

ce-session-extract

github.com/everyincAgent workflows25.8k132 installsUpdated today
Repository

About ce-session-extract

ce-session-extract is an agent skill for extracting a readable digest or error signals from a Claude Code, Codex, or Cursor session file. It avoids loading large JSONL transcripts into agent context by handling their format in scripts.

Key features

  1. 01Extract conversation skeletons
  2. 02Extract error signals
  3. 03Collapse consecutive repeated tool calls
  4. 04Limit output by line count
  5. 05Report parsing and event counts

Use cases

  1. 01Review conversation flow from one session
  2. 02Find recorded errors in a session
  3. 03Cap extracted output for context limits

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/everyinc/compound-engineering-plugin --skill ce-session-extract

After installing, type/ce-session-extractin Claude Code to confirm it loaded.

Bundled filesscripts/extract-errors.pyscripts/extract-skeleton.py

Details

From the project README

Session extract

Agent-facing primitive. Extract filtered content from a single Claude Code, Codex, or Cursor session file — either a conversation skeleton or error signals.

This skill exists so that agents do not read multi-megabyte session files into context. The scripts under scripts/ own the JSONL shape knowledge and emit a narrative-readable digest.

Arguments

Space-separated positional args:

  1. <file> — absolute path to a session JSONL file (typically a file value returned by ce-session-inventory).
  2. <mode> — skeleton or errors.
  3. <limit> (optional) — head:N or tail:N to cap output at N lines (e.g., head:200). Omit to return full extraction.

Execution

Skeleton mode — narrative of user messages, assistant text, and collapsed tool-call summaries:

cat <file> | python3 scripts/extract-skeleton.py

Errors mode — just error signals:

cat <file> | python3 scripts/extract-errors.py

If <limit> is head:N, pipe through head -n N. If tail:N, pipe through tail -n N. Apply the limit after the Python script, never before — the _meta line is emitted last and a head cap may drop it; that is acceptable when the caller asks for a head cap.

Return the raw stdout verbatim. Do not paraphrase, annotate, or synthesize — the caller does synthesis across multiple sessions.

What each mode returns

Skeleton

Narrative output with one logical event per block, separated by ---:

  • User messages (text only, no tool results, framework wrapper tags stripped)
  • Assistant text (no thinking/reasoning blocks — those are internal or encrypted)
  • Tool call summaries; 3+ consecutive same-name calls are collapsed (e.g., [tools] 5x Read (file1, file2, +3 more) -> all ok)

Ends with a _meta line: {"_meta": true, "lines": N, "parse_errors": N, "user": N, "assistant": N, "tool": N}.

Errors

One line per error, separated by ---:

  • Claude Code: tool results with is_error: true
  • Codex: exec_command_end events with non-zero exit or non-empty stderr
  • Cursor: always empty — Cursor agent transcripts do not log tool results

Ends with a _meta line: {"_meta": true, "lines": N, "parse_errors": N, "errors_found": N}.

Error handling

If the file cannot be read, let the error surface to the caller. If _meta reports parse_errors > 0, return the output as-is — partial extraction is still useful and the caller decides whether to widen the search or deep-dive further.

Comments

Markdown supported