Documentation
¶
Overview ¶
Package transcript reads an AI coding agent's on-disk conversation transcript and renders it to a neutral, agent-agnostic Markdown document.
It supports Claude Code and Codex as source agents. The rendered output is handed to a different agent during an in-place migration (see docs/design/2026-06-24-cross-agent-conversation-migration-design.md) so the new agent can continue the work with the full readable history.
Reading is deliberately defensive: undocumented, drifting formats and partially-written (live) files are tolerated by skipping unparseable lines and counting them, rather than failing.
Index ¶
- Constants
- Variables
- func BuildSeedPrompt(srcAgent, contextPath string) string
- func CodexRolloutID(path string) (string, bool)
- func CodexSessionIDSince(root, worktreePath string, since time.Time) (string, bool)
- func LocateCodexSince(worktreePath string, since time.Time) (string, bool)
- func LocateCodexSinceIn(root, worktreePath string, since time.Time) (string, bool)
- func Supported(agent string) bool
- type Conversation
- type RenderOptions
- type Role
- type ToolCall
- type Turn
Constants ¶
const ( AgentClaude = "claude" AgentCodex = "codex" )
Agent identifiers for supported source transcripts.
Variables ¶
var ErrNoTurns = errors.New("transcript contains no usable turns")
ErrNoTurns is returned by Read when a transcript parsed successfully but contained no usable conversation turns. Callers use this to fail fast before disrupting a running session.
var ErrUnsupportedAgent = errors.New("unsupported source agent for migration")
ErrUnsupportedAgent is returned for source agents without a reader.
Functions ¶
func BuildSeedPrompt ¶
BuildSeedPrompt is the short instruction passed to the target agent as its opening prompt, pointing it at the rendered context file.
func CodexRolloutID ¶
CodexRolloutID reads a rollout's session_meta id. Exported for the daemon's post-start id capture.
func CodexSessionIDSince ¶ added in v0.59.0
CodexSessionIDSince returns the native session id of the Codex rollout for a cwd created at/after `since`. Unlike LocateCodexSinceIn (newest-by-mtime), it refuses to guess when the (since, cwd) window contains rollouts with two or more DIFFERENT session ids — the concurrent shared-worktree / in-place case — returning ("", false) so the caller falls back to a non-pinned resume rather than cross-assigning another session's conversation. Pass root "" for the daemon default.
func LocateCodexSince ¶
LocateCodexSince returns the newest Codex rollout for a cwd whose mtime is at or after `since`. Used for post-start session-id capture: filtering by start time avoids picking a stale rollout from a prior session in the same cwd (a real hazard for in-place sessions and codex→codex migrations).
func LocateCodexSinceIn ¶ added in v0.59.0
LocateCodexSinceIn is LocateCodexSince scoped to an explicit Codex state root (CODEX_HOME). Pass "" to use the daemon's default root. This matters because the daemon-side scrape runs in the daemon process, but CODEX_HOME can be set per-session via the agent's launch env — reading the daemon's os.Getenv would scan the wrong directory and silently miss the rollout.
Types ¶
type Conversation ¶
type Conversation struct {
SrcAgent string
Turns []Turn
DroppedLines int // unparseable/skipped lines (format drift, partial tail)
}
Conversation is the parsed, normalized transcript.
func Read ¶
func Read(agent, agentSessionID, worktreePath string) (*Conversation, error)
Read locates and parses the transcript for a session. agentSessionID is the id graith tracks for the source agent (used to locate Claude transcripts); worktreePath is the session's working directory (used to locate Codex transcripts and as a fallback). Returns ErrNoTurns if the transcript parsed but yielded nothing usable.
func (*Conversation) Render ¶
func (c *Conversation) Render(opts RenderOptions) string
Render produces the neutral Markdown context document handed to the target agent. Turns are selected newest-first within the size budget but rendered chronologically so the document reads as a narrative.
type RenderOptions ¶
type RenderOptions struct {
// MaxBytes is the approximate size budget for the rendered body. When the
// transcript exceeds it, the oldest turns are elided (newest kept). 0 uses
// a default.
MaxBytes int
// MaxToolOutput caps each tool output block. 0 uses a default.
MaxToolOutput int
}
RenderOptions tunes the Markdown output.
Source Files