codex

package
v0.6.2 Latest Latest
Warning

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

 Go to latest Published: May 18, 2026 License: MIT Imports: 23 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"
	HookNamePostToolUse      = "post-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 HookTrustGaps added in v0.6.2 

func HookTrustGaps(repoRoot string) []string

HookTrustGaps returns the snake_case event labels declared in <repoRoot>/.codex/hooks.json that don't have a matching `[hooks.state."<hooks.json>:<event>:0:0"]` entry in the user's Codex config.toml — i.e. events the local user hasn't approved yet.

This is the structural form of the trust check: we don't recompute Codex's hook hash, we only look at key presence. That misses the "command changed but key is still there" case (status = Modified), but Codex's own startup warning catches those — our purpose here is to surface fresh additions like "you trusted three hooks last month but a new PostToolUse arrived" inside our SessionStart welcome.

Returns nil when:

  • .codex/hooks.json doesn't exist (entire isn't installed in this repo)
  • The user's config.toml can't be read
  • Every declared event already has a state entry

func MissingEntireHooks added in v0.6.2 

func MissingEntireHooks(repoRoot string) []string

MissingEntireHooks returns the snake_case event labels the CLI's canonical install ships today (SessionStart, UserPromptSubmit, Stop, PostToolUse) that aren't backed by an Entire-managed hook command in <repoRoot>/.codex/hooks.json. Surfaces drift when the user enabled Codex on an older release and the install set has since grown.

Returns nil when hooks.json is missing or unreadable — those cases are "Codex isn't enabled here", which is a different problem.

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 --json -. Prompt is piped via stdin (the trailing "-" tells codex to read from stdin). Stdout is newline-delimited JSON envelopes (one event per line); no chrome filter needed — each line is parsed directly into an Event.

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.

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"`
	PostToolUse      []MatcherGroup `json:"PostToolUse,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.