Skip to main content

Crate toolpath_codex

Crate toolpath_codex 

Source
Expand description

§toolpath-codex

Derive Toolpath provenance documents from Codex CLI session logs.

When Codex CLI writes your code, the rollout file — the reasoning, tool calls, shell output, and file patches — is the provenance. This crate reads those rollout files directly from ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl and maps them to Toolpath documents so every Codex-assisted change has a traceable origin.

§Overview

  • Reading: parse Codex rollout JSONL into strongly-typed RolloutLine records.
  • Provider: implements toolpath_convo::ConversationProvider, pairing function-call and tool-call outputs by call_id and folding exec_command_end / patch_apply_end events into Turn state.
  • Derivation: produces toolpath::v1::Path documents. File changes from patch_apply_end surface as sibling artifacts with the real unified diff as the raw perspective — no fidelity loss.

§Mapping

Codex sourceToolpath destination
session_meta.idpath.id = path-codex-<first-8>
session_meta.cwd + git.commit_hashpath.base = { file://<cwd>, ref: <commit> }
response_item.message (user)Step with actor: "human:user"
response_item.message (assistant)Step with actor: "agent:<model>"
response_item.message (developer)Step with actor: "system:codex"
response_item.reasoning.encrypted_contentTurn.thinking (opaque string)
response_item.function_call + function_call_output paired by call_idTurn.tool_uses[].{input,result}
response_item.custom_tool_call (e.g. apply_patch)same, with raw input string preserved
event_msg.patch_apply_end.changes[file]Sibling ArtifactChange on that step with raw = unified_diff
Other event_msg typesConversationEvent on the ConversationView

§Usage

use toolpath_codex::{CodexConvo, derive::{DeriveConfig, derive_path}};

let manager = CodexConvo::new();
let session_id = "019dabc6-8fef-7681-a054-b5bb75fcb97d";
let convo = manager.read_session(session_id)?;
let path = derive_path(&convo, &DeriveConfig::default());

§CLI

path list   codex [--json]
path derive codex --session <uuid|filename-stem> [--pretty]

§What’s not read

  • ~/.codex/state_5.sqlite — a cheap index over the rollout files. Could be used for fast listing on very large histories; not needed for v1.
  • ~/.codex/logs_1.sqlite and ~/.codex/log/codex-tui.log — application logs, not conversation content.
  • ~/.codex/history.jsonl — redundant user-prompt cache.
  • ~/.codex/memories, skills, shell_snapshots — not conversation.

See docs/agents/formats/codex.md in the workspace for the full on-disk format reference.

§Part of Toolpath

This crate is part of the Toolpath workspace. See also:

Re-exports§

pub use error::ConvoError;
pub use error::Result;
pub use io::ConvoIO;
pub use paths::PathResolver;
pub use reader::RolloutReader;
pub use types::BaseInstructions;
pub use types::ContentPart;
pub use types::CustomToolCall;
pub use types::CustomToolCallOutput;
pub use types::EventMsg;
pub use types::ExecCommandEnd;
pub use types::FunctionCall;
pub use types::FunctionCallOutput;
pub use types::GitInfo;
pub use types::Message;
pub use types::PatchApplyEnd;
pub use types::PatchChange;
pub use types::Reasoning;
pub use types::ResponseItem;
pub use types::RolloutItem;
pub use types::RolloutLine;
pub use types::SandboxPolicy;
pub use types::Session;
pub use types::SessionMeta;
pub use types::SessionMetadata;
pub use types::TokenCountEvent;
pub use types::TokenCountInfo;
pub use types::TokenUsage;
pub use types::TurnContext;
pub use provider::CodexConvo;
pub use provider::to_turn;
pub use provider::to_view;
pub use provider::tool_category;

Modules§

derive
Derive Toolpath documents from Codex CLI sessions.
error
io
Higher-level filesystem operations over PathResolver.
paths
Filesystem layout for Codex CLI state.
provider
Implementation of toolpath-convo traits for Codex sessions.
reader
Parse Codex rollout JSONL files.
types
On-disk schema for Codex CLI rollout JSONL files.