codex

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 27, 2026 License: MIT Imports: 17 Imported by: 0

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

Constants

This section is empty.

Variables

View Source 
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 

func DeleteAllSessions(workspacePath string) (int, error)

DeleteAllSessions deletes all Codex sessions within a workspace scope.

func DeleteSession 

func DeleteSession(workspacePath, sessionID string) error

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 

func SessionsDir(codexHome string) string

SessionsDir returns the root sessions directory for Codex CLI.

func SummarizeExecCommandForExplored 

func SummarizeExecCommandForExplored(cmd string) string

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.

func GetSessionMessages 

func GetSessionMessages(workspacePath, sessionID string, limit, offset int, order string) ([]Message, int, error)

GetSessionMessages returns paginated messages for a Codex session.

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.