Capture SDK Sessions

Agent Journal provides five vendor adapters that write compatible core events and portable traces. The Claude and Gemini adapters parse a typed SDK object: Claude consumes the Claude Agent SDK for Java and Gemini the gemini-cli-sdk published with Agent Client. Both require a Java 21 runtime, because those SDK dependencies are published as Java 21 bytecode. The Grok, Codex, and Antigravity adapters parse their CLI’s durable JSONL directly and carry no vendor SDK dependency, so they run on Java 17 like journal-core. All three produce an ordered tool trajectory; Gemini does not.

Claude Code

Add the adapter:

<dependency>
    <groupId>io.github.markpollack</groupId>
    <artifactId>claude-code-capture</artifactId>
    <version>1.8.0</version>
</dependency>

SessionLogParser converts an Iterator<ParsedMessage> from the Claude Code SDK into a PhaseCapture. The six-argument overload also writes a portable trace and controls modeled and raw content independently:

import io.github.markpollack.claude.agent.sdk.parsing.ParsedMessage;
import io.github.markpollack.journal.claude.PhaseCapture;
import io.github.markpollack.journal.claude.SessionLogParser;
import io.github.markpollack.journal.trace.TraceContentMode;
import io.github.markpollack.journal.trace.TraceRawMode;
import java.nio.file.Path;
import java.util.Iterator;

PhaseCapture phase = SessionLogParser.parse(
        response,
        "implement",
        promptText,
        Path.of(".agent-journal/traces/implement.jsonl"),
        TraceContentMode.TRUNCATED,
        TraceRawMode.NONE);

Here, response is an Iterator<ParsedMessage> returned by the SDK and promptText is the exact prompt or null. Record the capture into a durable journal with RunRecorder:

import io.github.markpollack.journal.Journal;
import io.github.markpollack.journal.claude.RunRecorder;
import io.github.markpollack.journal.storage.JsonFileStorage;
import java.nio.file.Path;

Journal.configure(new JsonFileStorage(Path.of(".agent-journal")));

try (RunRecorder recorder = new RunRecorder(
        Journal.run("capture-experiment").agent("claude-code").start())) {
    recorder.recordPhase(phase);
}

The recorder writes execution events to events.jsonl and per-step cost attribution to analysis.jsonl. It fails at finish when it produced derived events but the configured backend does not persist them durably. Call lenient() only when losing the derived stream after process exit is intentional.

Gemini CLI

Add the adapter:

<dependency>
    <groupId>io.github.markpollack</groupId>
    <artifactId>gemini-cli-capture</artifactId>
    <version>1.8.0</version>
</dependency>

GeminiSessionParser converts the Gemini SDK’s synchronous QueryResult into a GeminiPhaseCapture:

import io.github.markpollack.agents.geminisdk.types.QueryResult;
import io.github.markpollack.journal.Run;
import io.github.markpollack.journal.gemini.GeminiPhaseCapture;
import io.github.markpollack.journal.gemini.GeminiRunRecorder;
import io.github.markpollack.journal.gemini.GeminiSessionParser;

GeminiPhaseCapture phase = GeminiSessionParser.parse(
        result, "query", "summarize the repository");

new GeminiRunRecorder(run).recordPhase(phase);

Here, result is a QueryResult and run is an open Agent Journal Run. Configure JsonFileStorage if the derived StepCostEvent must survive process exit. Gemini’s typed SDK exposes result-level text, usage, cost, duration, model, and status, but it does not expose per-tool calls. The adapter therefore records one turn-level step and does not invent tool detail. It has no TraceRawMode because the typed Gemini message does not retain a verbatim wire envelope.

Grok CLI

Add the adapter:

<dependency>
    <groupId>io.github.markpollack</groupId>
    <artifactId>grok-cli-capture</artifactId>
    <version>1.8.0</version>
</dependency>

GrokSessionParser reads Grok’s ACP-shaped streaming-json output from a file or a BufferedReader:

import io.github.markpollack.journal.Run;
import io.github.markpollack.journal.grok.GrokPhaseCapture;
import io.github.markpollack.journal.grok.GrokRunRecorder;
import io.github.markpollack.journal.grok.GrokSessionParser;
import java.nio.file.Path;

GrokPhaseCapture phase = GrokSessionParser.parse(
        Path.of("grok-stream.jsonl"), "implement", promptText);

new GrokRunRecorder(run).recordPhase(phase);

The parser pairs tool_call and tool_call_update records by toolCallId, keeping both the tool name Grok reports and its ACP semantic kind. Grok’s stream carries a real session cost in end.total_cost_usd but no durable join from a turn to the tools it ran, so the session total is retained and attributed evenly across the captured tool steps.

Codex CLI

Add the adapter:

<dependency>
    <groupId>io.github.markpollack</groupId>
    <artifactId>codex-cli-capture</artifactId>
    <version>1.8.0</version>
</dependency>

CodexSessionParser reads a durable Codex rollout JSONL file:

import io.github.markpollack.journal.Run;
import io.github.markpollack.journal.codex.CodexPhaseCapture;
import io.github.markpollack.journal.codex.CodexRunRecorder;
import io.github.markpollack.journal.codex.CodexSessionParser;
import java.nio.file.Path;

CodexPhaseCapture phase = CodexSessionParser.parse(
        Path.of("rollout.jsonl"), "implement", promptText);

new CodexRunRecorder(run).recordPhase(phase);

Codex records most tool invocations under the outer function name exec, which would collapse every step into one undifferentiated name. The parser deliberately classifies the nested payload.input call instead, extracting exec_command arguments without evaluating them and assigning semantic names such as Search, Read, Inspect, Test, Build, and Git.

The classifier is conservative about shell syntax. Aliases, shell functions, quoted operators, and work hidden behind an interpreter fall back to Shell. The raw input and command are retained on the record, so callers can reclassify them later.

Codex rollout token counts, including cached and reasoning tokens, are preserved.

Antigravity CLI

Add the adapter:

<dependency>
    <groupId>io.github.markpollack</groupId>
    <artifactId>antigravity-cli-capture</artifactId>
    <version>1.8.0</version>
</dependency>

AntigravitySessionParser reads Antigravity’s streaming JSON:

import io.github.markpollack.journal.Run;
import io.github.markpollack.journal.antigravity.AntigravityPhaseCapture;
import io.github.markpollack.journal.antigravity.AntigravityRunRecorder;
import io.github.markpollack.journal.antigravity.AntigravitySessionParser;
import java.nio.file.Path;

AntigravityPhaseCapture phase = AntigravitySessionParser.parse(
        Path.of("antigravity-stream.jsonl"), "implement", promptText);

new AntigravityRunRecorder(run).recordPhase(phase);

The parser pairs active and terminal updates by step_index and handles both DONE and ERROR steps, recording parameters, output or error text, duration, and terminal token usage. Stable identities are derived from the conversation and step positions.

Cost provenance

Neither Codex nor Antigravity reports monetary cost in these streams. Their cost records are zero-valued and explicitly marked costAvailable=false with an unreported source, so a downstream reader can distinguish “this run cost nothing” from “this CLI never said.”

Portable trace modes

TraceContentMode controls content bodies on modeled trace lines:

Mode	Modeled content behavior
`FULL`	Writes complete assistant text, thinking text, and tool-result content
`TRUNCATED`	Default; caps each modeled content body at 60,000 characters
`LENGTHS`	Omits those modeled content bodies and records their lengths

TraceRawMode is Claude-only and orthogonal:

Mode	Raw vendor messages
`NONE`	Default; no raw vendor-message lines
`FULL`	Writes each available vendor message as an unredacted `raw` line

All trace modes require a data-handling decision. The capture record and journal events can contain the caller-supplied prompt text. Tool inputs are present on portable tool_use lines even in LENGTHS mode. TRUNCATED and FULL portable traces can include assistant text, file contents, tool results, and command output. TraceRawMode.FULL adds the complete available vendor message and can include fields omitted from the typed model. Treat trace and journal files as sensitive, restrict filesystem access, and keep them out of version control.

Two schemas

Do not conflate the two JSONL formats:

Canonical journal streams use @type and currently have schema version 1.
Portable capture traces use type, ts, and seq and currently have schema version 2.

Both formats have their own header and evolution contract.

Projects

AgentWorks

Supporting Projects

Migration

Explorations

Older / Inactive Projects

Claude Code

Gemini CLI

Grok CLI

Codex CLI

Antigravity CLI

Cost provenance

Portable trace modes

Two schemas

​Claude Code

​Gemini CLI

​Grok CLI

​Codex CLI

​Antigravity CLI

​Cost provenance

​Portable trace modes

​Two schemas

Claude Code

Gemini CLI

Grok CLI

Codex CLI

Antigravity CLI

Cost provenance

Portable trace modes

Two schemas