Crate toolpath_pi 

toolpath-pi

Read Pi coding-agent session logs and derive Toolpath provenance documents.

Pi stores sessions as JSONL files at ~/.pi/agent/sessions/--<encoded-cwd>--/<timestamp>_<uuid>.jsonl. Each entry forms a tree via id/parentId fields, enabling in-place branching. Sessions can link to parent sessions via a parentSession file path in the session header.

This crate implements the toolpath_convo::ConversationProvider trait and a derive_path wrapper that produces a toolpath::v1::Path via the shared derivation in toolpath_convo::derive_path.

Quick example

use toolpath_pi::PiConvo;

let manager = PiConvo::new();
let session = manager
    .most_recent_session("/Users/alex/project")
    .unwrap()
    .expect("no Pi sessions");
let view = manager.to_view(&session);

Listing sessions

list_sessions returns lightweight SessionMeta summaries — id, timestamp, file path, entry count, and first_user_message (the first non-empty user-prompt text). The last field is what makes the listing useful for “pick a session by topic” surfaces like an fzf picker.

use toolpath_pi::PiConvo;

let manager = PiConvo::new();
for meta in manager.list_sessions("/Users/alex/project").unwrap() {
    println!(
        "{}: {}",
        meta.id,
        meta.first_user_message.as_deref().unwrap_or("(no prompt)"),
    );
}

Re-exports

pub use derive::derive_graph;

pub use derive::derive_path;

pub use derive::derive_project;

pub use error::PiError;

pub use error::Result;

pub use paths::PathResolver;

pub use provider::session_to_view;

pub use reader::PiSession;

pub use reader::SessionMeta;

pub use types::AgentMessage;

pub use types::ContentBlock;

pub use types::CostBreakdown;

pub use types::Entry;

pub use types::EntryBase;

pub use types::SessionHeader;

pub use types::Usage;

Modules

derive

Thin wrapper: PiSession → ConversationView → toolpath_convo::derive.

error

Error types for toolpath-pi.

io

Filesystem enumeration for Pi sessions.

paths

Path resolution for Pi’s on-disk layout.

provider

ConversationProvider bridge: map Pi sessions to toolpath_convo::ConversationView.

reader

JSONL parsing + session assembly for Pi session files.

types

Pi session schema (format version 3).

Structs

DeriveConfig

Configuration for derive_path.

PiConvo

High-level interface for reading Pi sessions.