codex

package
v0.6.1 Latest Latest
Warning

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

 Go to latest Published: May 7, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package codex implements the Agent interface for OpenAI's Codex CLI.

Index

Constants

View Source 
const (
	HookNameSessionStart     = "session-start"
	HookNameUserPromptSubmit = "user-prompt-submit"
	HookNameStop             = "stop"
	HookNamePreToolUse       = "pre-tool-use"
)

Codex hook names — these become subcommands under `entire hooks codex`

View Source 
const HooksFileName = "hooks.json"

HooksFileName is the hooks config file used by Codex.

Variables

This section is empty.

Functions

func FilterLine added in v0.6.1 

func FilterLine(line string) (string, bool)

FilterLine applies all codex-specific chrome filters to a single line. It returns the cleaned line and true if the line should be emitted, or ("", false) if the line is chrome and must be dropped.

Filtering order:

  1. Strip CSI/ANSI escape sequences.
  2. Drop blank lines after stripping.
  3. Drop banner/header lines.
  4. Drop exec-block lines (anchored to avoid false positives).
  5. Drop hook-firing notice lines.
  6. Drop timestamped error/log lines.

func NewCodexAgent 

func NewCodexAgent() agent.Agent

NewCodexAgent creates a new Codex agent instance.

func NewReviewer added in v0.6.1 

func NewReviewer() *reviewtypes.ReviewerTemplate

NewReviewer returns the AgentReviewer for codex.

Argv shape: codex exec --skip-git-repo-check -. Prompt is piped via stdin (the trailing "-" tells codex to read from stdin). Stdout includes chrome (banners, hook notices, exec blocks, CSI sequences) that output_filter.go strips before emitting AssistantText events.

func SanitizePortableTranscript added in v0.5.4 

func SanitizePortableTranscript(data []byte) []byte

SanitizePortableTranscript strips encrypted history fragments that cannot be replayed when Entire reconstructs a Codex rollout outside its original session context.

func Strip added in v0.6.1 

func Strip(r io.Reader) io.Reader

Strip wraps r in a filtered reader that removes codex chrome line-by-line. The returned reader emits only lines that pass FilterLine, each terminated by a newline.

Types

type CodexAgent 

type CodexAgent struct {
	CommandRunner agent.TextCommandRunner
}

CodexAgent implements the Agent interface for OpenAI's Codex CLI.

func (*CodexAgent) AreHooksInstalled 

func (c *CodexAgent) AreHooksInstalled(ctx context.Context) bool

AreHooksInstalled checks if Entire hooks are installed in Codex hooks.json.

func (*CodexAgent) CalculateTokenUsage 

func (c *CodexAgent) CalculateTokenUsage(transcriptData []byte, fromOffset int) (*agent.TokenUsage, error)

CalculateTokenUsage computes token usage from the transcript starting at the given line offset. Codex reports cumulative total_token_usage, so we compute the delta between the last token_count at/before the offset and the last token_count after the offset.

func (*CodexAgent) ChunkTranscript 

func (c *CodexAgent) ChunkTranscript(_ context.Context, content []byte, maxSize int) ([][]byte, error)

ChunkTranscript splits a JSONL transcript at line boundaries.

func (*CodexAgent) Description 

func (c *CodexAgent) Description() string

Description returns a human-readable description.

func (*CodexAgent) DetectPresence 

func (c *CodexAgent) DetectPresence(ctx context.Context) (bool, error)

DetectPresence checks if Codex is configured in the repository.

func (*CodexAgent) DiscoverReviewSkills added in v0.6.1 

func (c *CodexAgent) DiscoverReviewSkills(_ context.Context) ([]agent.DiscoveredSkill, error)

DiscoverReviewSkills is a stub until the Codex on-disk plugin layout is verified against codex-rs source (see codex-rs/tui/src/slash_command.rs). Returns (nil, nil) so the picker treats Codex as "built-ins + install hint only" for Phase 1.

func (*CodexAgent) ExtractModifiedFilesFromOffset 

func (c *CodexAgent) ExtractModifiedFilesFromOffset(path string, startOffset int) (files []string, currentPosition int, err error)

ExtractModifiedFilesFromOffset extracts files modified since a given line offset.

func (*CodexAgent) ExtractPrompts 

func (c *CodexAgent) ExtractPrompts(sessionRef string, fromOffset int) ([]string, error)

ExtractPrompts returns user prompts from the transcript starting at the given offset.

func (*CodexAgent) FormatResumeCommand 

func (c *CodexAgent) FormatResumeCommand(sessionID string) string

FormatResumeCommand returns the command to resume a Codex session.

func (*CodexAgent) GenerateText added in v0.5.6 

func (c *CodexAgent) GenerateText(ctx context.Context, prompt string, model string) (string, error)

GenerateText sends a prompt to the Codex CLI and returns the raw text response.

func (*CodexAgent) GetSessionDir 

func (c *CodexAgent) GetSessionDir(_ string) (string, error)

GetSessionDir returns the directory where Codex stores session transcripts. Codex stores transcripts under CODEX_HOME/sessions/YYYY/MM/DD/.

func (*CodexAgent) GetSessionID 

func (c *CodexAgent) GetSessionID(input *agent.HookInput) string

GetSessionID extracts the session ID from hook input.

func (*CodexAgent) GetTranscriptPosition 

func (c *CodexAgent) GetTranscriptPosition(path string) (int, error)

GetTranscriptPosition returns the current line count of a Codex rollout transcript.

func (*CodexAgent) HookNames 

func (c *CodexAgent) HookNames() []string

HookNames returns the hook verbs Codex supports.

func (*CodexAgent) InstallHooks 

func (c *CodexAgent) InstallHooks(ctx context.Context, localDev bool, force bool) (int, error)

InstallHooks installs Codex hooks in .codex/hooks.json.

func (*CodexAgent) IsPreview 

func (c *CodexAgent) IsPreview() bool

IsPreview returns true because this is a new integration.

func (*CodexAgent) LaunchCmd added in v0.6.1 

func (c *CodexAgent) LaunchCmd(ctx context.Context, initialPrompt string) (*exec.Cmd, error)

LaunchCmd builds an exec.Cmd for `codex "<initialPrompt>"`. Stdio is wired to the caller's TTY so the agent runs foreground and the user interacts normally. The call site is expected to Run() and wait. Hooks inherit the parent environment.

func (*CodexAgent) Name 

func (c *CodexAgent) Name() types.AgentName

Name returns the agent registry key.

func (*CodexAgent) ParseHookEvent 

func (c *CodexAgent) ParseHookEvent(_ context.Context, hookName string, stdin io.Reader) (*agent.Event, error)

ParseHookEvent translates a Codex hook into a normalized lifecycle Event. Returns nil if the hook has no lifecycle significance.

func (*CodexAgent) ProtectedDirs 

func (c *CodexAgent) ProtectedDirs() []string

ProtectedDirs returns directories that Codex uses for config/state.

func (*CodexAgent) ReadSession 

func (c *CodexAgent) ReadSession(input *agent.HookInput) (*agent.AgentSession, error)

ReadSession reads a session from Codex's storage (JSONL rollout file).

func (*CodexAgent) ReadTranscript 

func (c *CodexAgent) ReadTranscript(sessionRef string) ([]byte, error)

ReadTranscript reads the raw JSONL transcript bytes for a session.

func (*CodexAgent) ReassembleTranscript 

func (c *CodexAgent) ReassembleTranscript(chunks [][]byte) ([]byte, error)

ReassembleTranscript concatenates JSONL chunks with newlines.

func (*CodexAgent) ResolveRestoredSessionFile added in v0.5.4 

func (c *CodexAgent) ResolveRestoredSessionFile(sessionDir, agentSessionID string, transcript []byte) (string, error)

ResolveRestoredSessionFile returns the canonical Codex rollout path for a restored session so `codex resume <id>` can rediscover it.

func (*CodexAgent) ResolveSessionFile 

func (c *CodexAgent) ResolveSessionFile(sessionDir, agentSessionID string) string

ResolveSessionFile returns the path to a Codex session transcript file. Codex provides the transcript path directly in hook payloads as an absolute path. When only a session ID is available, attach/rewind must recover it from the sessions/YYYY/MM/DD/rollout-...-<session-id>.jsonl layout.

func (*CodexAgent) Type 

func (c *CodexAgent) Type() types.AgentType

Type returns the agent type identifier.

func (*CodexAgent) UninstallHooks 

func (c *CodexAgent) UninstallHooks(ctx context.Context) error

UninstallHooks removes Entire hooks from Codex hooks.json.

func (*CodexAgent) WriteHookResponse 

func (c *CodexAgent) WriteHookResponse(message string) error

WriteHookResponse outputs a JSON hook response to stdout. Codex reads the systemMessage field and displays it to the user.

func (*CodexAgent) WriteSession 

func (c *CodexAgent) WriteSession(_ context.Context, session *agent.AgentSession) error

WriteSession writes a session to Codex's storage (JSONL rollout file).

type HookEntry 

type HookEntry struct {
	Type    string `json:"type"`
	Command string `json:"command"`
	Timeout int    `json:"timeout,omitempty"`
}

HookEntry represents a single hook command in the config.

type HookEvents 

type HookEvents struct {
	SessionStart     []MatcherGroup `json:"SessionStart,omitempty"`
	UserPromptSubmit []MatcherGroup `json:"UserPromptSubmit,omitempty"`
	Stop             []MatcherGroup `json:"Stop,omitempty"`
	PreToolUse       []MatcherGroup `json:"PreToolUse,omitempty"`
}

HookEvents contains the hook configurations by event type.

type HooksFile 

type HooksFile struct {
	Hooks HookEvents `json:"hooks"`
}

HooksFile represents the .codex/hooks.json structure.

type MatcherGroup 

type MatcherGroup struct {
	Matcher *string     `json:"matcher"`
	Hooks   []HookEntry `json:"hooks"`
}

MatcherGroup groups hooks under an optional matcher pattern.

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.