Documentation
¶
Overview ¶
Package codex provides helpers for parsing Codex CLI session logs into a normalized conversation stream that matches cdev's existing Claude-oriented UI primitives (text/thinking/tool_use/tool_result).
Package codex provides Codex CLI session parsing, discovery, and indexing.
Package codex provides Codex CLI session parsing and discovery helpers.
Package codex provides Codex CLI session streaming for real-time updates.
Index ¶
- Variables
- func DefaultCodexHome() string
- func DeleteAllSessions(workspacePath string) (int, error)
- func DeleteSession(workspacePath, sessionID string) error
- func FormatMessageJSON(role, content string) (json.RawMessage, error)
- func ParseSessionFile(path string) (SessionInfo, []Message, error)
- func SessionsDir(codexHome string) string
- func SummarizeExecCommandForExplored(cmd string) string
- type ConversationItem
- type IndexCache
- func (c *IndexCache) FindSessionByID(sessionID string) (*SessionIndexEntry, error)
- func (c *IndexCache) GetAllSessions() ([]SessionIndexEntry, error)
- func (c *IndexCache) GetProjectIndex(projectPath string) (*SessionIndex, error)
- func (c *IndexCache) GetSessionsForProject(projectPath string) ([]SessionIndexEntry, error)
- func (c *IndexCache) InvalidateByPath(path string) error
- func (c *IndexCache) ListProjects() ([]ProjectSummary, error)
- func (c *IndexCache) Refresh() error
- type Message
- type ProjectSummary
- type SessionIndex
- type SessionIndexEntry
- type SessionInfo
- type SessionStreamer
Constants ¶
This section is empty.
Variables ¶
var ErrProjectNotFound = errors.New("project not found")
ErrProjectNotFound indicates the requested project has no indexed Codex sessions.
Functions ¶
func DefaultCodexHome ¶
func DefaultCodexHome() string
DefaultCodexHome resolves CODEX_HOME (or ~/.codex by default).
func DeleteAllSessions ¶
DeleteAllSessions deletes all Codex sessions within a workspace scope.
func DeleteSession ¶
DeleteSession deletes a specific Codex session by ID.
func FormatMessageJSON ¶
func FormatMessageJSON(role, content string) (json.RawMessage, error)
FormatMessageJSON builds a minimal message JSON payload for clients.
func ParseSessionFile ¶
func ParseSessionFile(path string) (SessionInfo, []Message, error)
ParseSessionFile parses a Codex JSONL session file.
func SessionsDir ¶
SessionsDir returns the root sessions directory for Codex CLI.
func SummarizeExecCommandForExplored ¶
SummarizeExecCommandForExplored converts a shell command into a compact "Explored" summary line (Search/List/Read) when appropriate.
Types ¶
type ConversationItem ¶
type ConversationItem struct {
// Line is the 1-based line number in the JSONL file (stable for append-only logs).
Line int
// Timestamp is the entry timestamp (RFC3339/RFC3339Nano string).
Timestamp string
// Role is "user" or "assistant".
Role string
// IsContextCompaction marks synthetic compaction boundary/summary messages.
IsContextCompaction bool
// IsTurnAborted marks synthetic interruption boundary messages.
IsTurnAborted bool
// Content are Claude-like content blocks (text/thinking/tool_use/tool_result).
Content []events.ClaudeMessageContent
}
ConversationItem is a normalized, UI-ready item derived from Codex CLI JSONL logs. It is intentionally shaped to be convertible into: - `claude_message` events (for live UI streaming) - `session/messages` synthetic message payloads - `session/elements` for rich timeline rendering
func ParseConversationLine ¶
func ParseConversationLine(line string) (*ConversationItem, error)
ParseConversationLine parses a single Codex CLI JSONL line into a normalized conversation item. Returns (nil, nil) for lines that aren't relevant for UI rendering.
func ReadConversationItems ¶
func ReadConversationItems(path string) ([]ConversationItem, error)
ReadConversationItems reads a Codex session JSONL file and returns all normalized conversation items.
type IndexCache ¶
type IndexCache struct {
// contains filtered or unexported fields
}
IndexCache provides cached access to Codex session indexes.
func GetGlobalIndexCache ¶
func GetGlobalIndexCache() *IndexCache
GetGlobalIndexCache returns the global index cache singleton.
func NewIndexCache ¶
func NewIndexCache(codexHome string) *IndexCache
NewIndexCache creates a new index cache.
func (*IndexCache) FindSessionByID ¶
func (c *IndexCache) FindSessionByID(sessionID string) (*SessionIndexEntry, error)
FindSessionByID searches all projects for a session by ID.
func (*IndexCache) GetAllSessions ¶
func (c *IndexCache) GetAllSessions() ([]SessionIndexEntry, error)
GetAllSessions returns all sessions from all projects. Sessions are sorted by modification time (most recent first). Use this when you want to list sessions without filtering by project path.
func (*IndexCache) GetProjectIndex ¶
func (c *IndexCache) GetProjectIndex(projectPath string) (*SessionIndex, error)
GetProjectIndex returns the session index for a specific project.
func (*IndexCache) GetSessionsForProject ¶
func (c *IndexCache) GetSessionsForProject(projectPath string) ([]SessionIndexEntry, error)
GetSessionsForProject returns all sessions for a specific project path.
func (*IndexCache) InvalidateByPath ¶
func (c *IndexCache) InvalidateByPath(path string) error
InvalidateByPath removes a single session from the in-memory cache by its file path. Use this after deleting a session file to keep the cache consistent without a full directory rescan.
func (*IndexCache) ListProjects ¶
func (c *IndexCache) ListProjects() ([]ProjectSummary, error)
ListProjects returns all projects with Codex sessions.
func (*IndexCache) Refresh ¶
func (c *IndexCache) Refresh() error
Refresh forces a refresh of the index cache.
type Message ¶
type Message struct {
Role string `json:"role"`
Content string `json:"content"`
Timestamp time.Time `json:"timestamp"`
Source string `json:"source"`
SessionID string `json:"session_id"`
}
Message is a normalized Codex session message.
type ProjectSummary ¶
type ProjectSummary struct {
// ProjectPath is the working directory.
ProjectPath string `json:"projectPath"`
// EncodedPath is the URL-safe encoded path (like Claude Code).
EncodedPath string `json:"encodedPath"`
// SessionCount is the number of sessions in this project.
SessionCount int `json:"sessionCount"`
// TotalSize is the total size of all session files in bytes.
TotalSize int64 `json:"totalSize"`
// LastActivity is the most recent session modification time.
LastActivity time.Time `json:"lastActivity"`
// GitRepo is the repository URL (from most recent session).
GitRepo string `json:"gitRepo,omitempty"`
// GitBranch is the current/last branch (from most recent session).
GitBranch string `json:"gitBranch,omitempty"`
}
ProjectSummary represents a project with its session statistics.
type SessionIndex ¶
type SessionIndex struct {
// Version is the index format version.
Version int `json:"version"`
// Entries are the indexed sessions.
Entries []SessionIndexEntry `json:"entries"`
// OriginalPath is the project directory path.
OriginalPath string `json:"originalPath"`
// LastIndexed is when the index was last built.
LastIndexed time.Time `json:"lastIndexed"`
}
SessionIndex represents the index for a project (like Claude Code's sessions-index.json).
type SessionIndexEntry ¶
type SessionIndexEntry struct {
// SessionID is the unique session identifier (UUID).
SessionID string `json:"sessionId"`
// FullPath is the absolute path to the session file.
FullPath string `json:"fullPath"`
// FileMtime is the file modification time in milliseconds.
FileMtime int64 `json:"fileMtime"`
// FirstPrompt is the first user message in the session.
FirstPrompt string `json:"firstPrompt,omitempty"`
// Summary is the last assistant message or agent summary.
Summary string `json:"summary,omitempty"`
// MessageCount is the number of user/assistant message pairs.
MessageCount int `json:"messageCount"`
// Created is when the session was created.
Created time.Time `json:"created"`
// Modified is when the session was last modified.
Modified time.Time `json:"modified"`
// GitBranch is the git branch at session start.
GitBranch string `json:"gitBranch,omitempty"`
// GitCommit is the git commit hash at session start.
GitCommit string `json:"gitCommit,omitempty"`
// GitRepo is the repository URL.
GitRepo string `json:"gitRepo,omitempty"`
// ProjectPath is the working directory (cwd) for this session.
ProjectPath string `json:"projectPath"`
// ModelProvider is the AI provider (openai, anthropic, etc.).
ModelProvider string `json:"modelProvider,omitempty"`
// Model is the specific model used.
Model string `json:"model,omitempty"`
// CLIVersion is the Codex CLI version.
CLIVersion string `json:"cliVersion,omitempty"`
// FileSize is the session file size in bytes.
FileSize int64 `json:"fileSize,omitempty"`
// LineCount is the number of lines in the session file.
LineCount int `json:"lineCount,omitempty"`
}
SessionIndexEntry represents a single session in the project index. Modeled after Claude Code's sessions-index.json entries.
type SessionInfo ¶
type SessionInfo struct {
SessionID string `json:"session_id"`
Summary string `json:"summary"`
MessageCount int `json:"message_count"`
LastUpdated time.Time `json:"last_updated"`
WorkspacePath string `json:"workspace_path"`
}
SessionInfo describes a Codex CLI session file.
func FindSessionByID ¶
func FindSessionByID(workspacePath, sessionID string) (*SessionInfo, string, error)
FindSessionByID locates a session by ID within a workspace scope. Returns session info and the file path for the matching session.
func ListSessionsForWorkspace ¶
func ListSessionsForWorkspace(workspacePath string) ([]SessionInfo, error)
ListSessionsForWorkspace returns sessions whose cwd is under the workspace path.
type SessionStreamer ¶
type SessionStreamer struct {
// contains filtered or unexported fields
}
SessionStreamer watches a Codex session file and streams new messages.
func NewSessionStreamer ¶
func NewSessionStreamer(workspacePath string, hub ports.EventHub) *SessionStreamer
NewSessionStreamer creates a new Codex session streamer.
func (*SessionStreamer) Close ¶
func (s *SessionStreamer) Close()
Close stops the streamer and releases resources.
func (*SessionStreamer) GetWatchedSession ¶
func (s *SessionStreamer) GetWatchedSession() string
GetWatchedSession returns the currently watched session ID.
func (*SessionStreamer) UnwatchSession ¶
func (s *SessionStreamer) UnwatchSession()
UnwatchSession stops watching the current session.
func (*SessionStreamer) WatchSession ¶
func (s *SessionStreamer) WatchSession(sessionID string) error
WatchSession starts watching a Codex session for new messages.