Documentation
¶
Overview ¶
Package sessions finds the coding-agent sessions recorded for a repository on this machine and maps each into the normalised session.Graph.
Claude Code, Codex and Cursor sessions are read from their stores in the home directory; Entire sessions from the checkpoint branch in the clone. Each vendor's parser lives in its own package; this one only decides which stores to read and which trees are trustworthy enough to return.
Index ¶
- Constants
- Variables
- func Fuller(a, b Session) bool
- func HasTranscript(graph *session.Graph) bool
- func IsGenerationRun(graph *session.Graph) bool
- func Load(ctx context.Context, dir string, opts Options) ([]Session, Report, error)
- func Map(s collector.Session) (*session.Graph, []string, error)
- func ParseSource(name string) (vendors.Slug, error)
- func Root(graph *session.Graph) *session.Session
- type Checkpoints
- func (c *Checkpoints) Close()
- func (c *Checkpoints) Load(ctx context.Context, id string) ([]Session, []Failure, error)
- func (c *Checkpoints) Located(ctx context.Context, ids []string) (map[string]bool, error)
- func (c *Checkpoints) Sessions(ctx context.Context, ids []string) (map[string][]string, error)
- type Failure
- type Options
- type Report
- type Session
Constants ¶
const Entire vendors.Slug = "entire"
Entire is the source slug of sessions read from Entire checkpoints. It is a recorder rather than an agent, so vendors does not list it; Session.Vendor names the agent that ran.
const GenerationRunMarker = "<!-- baum:generation-run -->"
GenerationRunMarker starts the prompt of every agent run baum itself starts to generate a review. Such a run is recorded in the same stores as the developer's own sessions, in a worktree of the same clone, so the marker is what keeps it from being taken as evidence about the pull request it reviews.
Variables ¶
var ErrUnbalanced = errors.New("mapper did not account for every record")
ErrUnbalanced reports a tree whose mapper could not account for every record it read. Such a tree understates what happened and is not returned.
var Sources = []vendors.Slug{vendors.ClaudeCode, vendors.Codex, vendors.Cursor, Entire}
Sources lists every source Load reads, in the order it reads them.
Functions ¶
func Fuller ¶
Fuller reports whether a is a better reading of a session than b: one with a transcript over one without, and otherwise the one written later.
func HasTranscript ¶
HasTranscript reports whether a graph records anything the agent did: a model call, an assistant message or a tool use. A snapshot Entire wrote with only its metadata and the prompt has none.
func IsGenerationRun ¶
IsGenerationRun reports whether graph is one of baum's own generation runs: a user input of its top-level session begins with GenerationRunMarker. A prompt that only mentions the marker further in does not count.
func Load ¶
Load returns every session recorded for the git repository containing dir, mapped and ordered by modification time.
A session belongs to the repository when it was recorded in any of the clone's working trees, the main checkout or a linked worktree, whichever of them dir is in; git's own list of worktrees says which those are. Each Entire session is returned once, from the newest checkpoint that recorded it, and not at all when the agent's own store holds it.
func Map ¶
Map turns one discovered session into its graph. The notes are the mapper's remarks; an error means the tree must not be used.
func ParseSource ¶
ParseSource accepts a source slug as typed on the command line.
Types ¶
type Checkpoints ¶
type Checkpoints struct {
// contains filtered or unexported fields
}
Checkpoints is the checkpoints of a clone, opened once for several lookups. It reads the per-checkpoint refs (refs/entire/checkpoints/*) and the local checkpoint branch or a remote-tracking copy of it, a checkpoint in both being read from its ref, in a private repository, and never fetches. Close releases it.
func OpenCheckpoints ¶
func OpenCheckpoints(ctx context.Context, dir string) (*Checkpoints, error)
OpenCheckpoints opens the checkpoints of the clone containing dir. It returns nil and no error when the clone has neither checkpoint refs nor a checkpoint branch.
func (*Checkpoints) Load ¶
Load maps the sessions one checkpoint in the clone records, as Load maps an Entire session, with no Since applied. A session that cannot be mapped is a Failure; an error is a checkpoint that could not be read at all.
func (*Checkpoints) Located ¶
Located reports which of ids the clone holds, by canonical id, whether or not its metadata can be read: a checkpoint Sessions leaves out that Located reports is unreadable, and one it does not report is not in the clone.
func (*Checkpoints) Sessions ¶
Sessions returns, for each of ids that is a checkpoint in the clone, keyed by its canonical id (entirecheckpoint.CanonicalID), the ids of the sessions it records, each once, in the order it lists them. It reads checkpoint metadata only. A checkpoint the clone does not hold, or whose metadata cannot be read, is absent from the result.
type Failure ¶
Failure is one session discovery found but could not map. It never costs its siblings: Load returns the sessions it could map alongside these.
type Options ¶
type Options struct {
// PreviousPaths are directories the repository used to live at, so
// sessions recorded there still count.
PreviousPaths []string
// Sources restricts the stores read; empty means Sources.
Sources []vendors.Slug
// Since drops sessions last modified before it.
Since time.Time
// Store overrides, mainly for tests. Empty means the vendor default.
ClaudeProjectsDir string
CodexSessionsDir string
CursorStorePaths []string
}
Options narrows what Load reads. Zero values mean everything.
type Report ¶
type Report struct {
// Skipped are files discovery could not read.
Skipped []model.SkippedFile
// Failures are sessions that were found but did not map.
Failures []Failure
// EntireCommit is the checkpoint branch commit read, empty when the clone
// has none (checkpoints held only in refs/entire/checkpoints/* leave it
// empty).
EntireCommit string
}
Report is what Load dropped along the way.
type Session ¶
type Session struct {
// Source is the store the session was read from; Vendor the agent that
// ran. They differ for Entire, which records other agents' sessions.
Source vendors.Slug
Vendor string
ID string
// Path is the transcript file, the Cursor store plus composer id, or the
// Entire checkpoint id.
Path string
RepoRoot string
WorktreeRoot string
ModifiedAt time.Time
Graph *session.Graph
// Notes are the mapper's remarks about the tree: a subagent nothing
// spawned, a rollout that could not be read.
Notes []string
}
Session is one mapped session tree.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package claudetranscript reads Claude Code transcripts as typed, classified lines.
|
Package claudetranscript reads Claude Code transcripts as typed, classified lines. |
|
entire
Package entire finds Entire checkpoints in the user's own clone.
|
Package entire finds Entire checkpoints in the user's own clone. |
|
Package cursorsession maps Cursor's typed SQLite records into the shared session model.
|
Package cursorsession maps Cursor's typed SQLite records into the shared session model. |
|
Package cursortranscript reads Cursor's global SQLite conversation store as typed records.
|
Package cursortranscript reads Cursor's global SQLite conversation store as typed records. |
|
Package entirecheckpoint reads one Entire checkpoint tree without assigning session-model meaning to its records, and the checkpoint ids commits name in their Entire-Checkpoint trailers.
|
Package entirecheckpoint reads one Entire checkpoint tree without assigning session-model meaning to its records, and the checkpoint ids commits name in their Entire-Checkpoint trailers. |
|
Package entiresession maps Entire checkpoint snapshots into shared session graphs, delegating native transcripts where a mapper exists.
|
Package entiresession maps Entire checkpoint snapshots into shared session graphs, delegating native transcripts where a mapper exists. |
|
Package prompttext decides what part of a recorded user turn is a prompt somebody actually typed.
|
Package prompttext decides what part of a recorded user turn is a prompt somebody actually typed. |
|
Package session defines the vendor-agnostic session model.
|
Package session defines the vendor-agnostic session model. |
|
Package sourcepath handles filesystem paths recorded on a machine whose OS may differ from the process reading them.
|
Package sourcepath handles filesystem paths recorded on a machine whose OS may differ from the process reading them. |
|
Package sqliteread reads local SQLite stores that agents keep their session data in — today, Cursor's `state.vscdb` chat store.
|
Package sqliteread reads local SQLite stores that agents keep their session data in — today, Cursor's `state.vscdb` chat store. |
|
Package vendors holds the canonical agent slugs the platform stores and groups by.
|
Package vendors holds the canonical agent slugs the platform stores and groups by. |