codex

Documentation

Overview

Package codex adapts the OpenAI Codex CLI (`codex`) to codexmon's agent contract: it locates the binary, injects the `exec --json` / `--output-last-message` flags that make a run observable, and parses codex's JSONL event stream into the normalized agent.Event the monitor consumes.

Index

• func Analyze(args []string, resultFile string, allowJSON bool) agent.Analysis
• func Subcommand(args []string) string
• type Event
  • func Parse(line string) (Event, bool)
  • func (ev Event) Describe() (phase agent.Phase, summary string)
• type FileChange
• type Item
• type Provider
  • func (Provider) Analyze(args []string, resultFile string, allowJSON bool) agent.Analysis
  • func (Provider) BinCandidates() []string
  • func (Provider) BinEnv() string
  • func (Provider) Doctor(bin string, run agent.RunFunc) agent.DoctorReport
  • func (Provider) Name() string
  • func (Provider) ParseLine(line string) (agent.Event, bool)
  • func (Provider) ReviewArgs(spec agent.ReviewSpec) ([]string, error)

Functions

func Analyze

func Analyze(args []string, resultFile string, allowJSON bool) agent.Analysis

Analyze decides how to run codex. For `exec`, it defaults the model (and, only when it also picks the model, the reasoning effort) unless the caller supplied that setting via -m/--model, -c/--config, or a -p/--profile. When JSON is not disabled, it also injects `--json` (for event monitoring) and, unless the caller already set one, `--output-last-message <resultFile>` as a reliable final-answer backup. Exec-specific flags are placed right after the `exec` token, where they apply to exec and any of its sub-subcommands (review/resume).

func Subcommand

func Subcommand(args []string) string

Subcommand returns the first positional token in args — codex's subcommand (e.g. "exec", "review", "login") — skipping flags and their values. Returns "" if there is no positional (bare `codex`, which opens the TUI).

Types

type Event

type Event struct {
	Type     string          `json:"type"`
	ThreadID string          `json:"thread_id,omitempty"`
	Item     *Item           `json:"item,omitempty"`
	Usage    *agent.Usage    `json:"usage,omitempty"`
	Error    json.RawMessage `json:"error,omitempty"`
	Message  string          `json:"message,omitempty"`
}

Event is a single line of the `codex exec --json` stream.

func Parse

func Parse(line string) (Event, bool)

Parse decodes a single JSONL line. ok is false for blank lines or lines that are not valid JSON objects (Codex occasionally prints stray banner text).

func (Event) Describe

func (ev Event) Describe() (phase agent.Phase, summary string)

Describe returns the phase implied by an event plus a one-line, human-readable summary. phase is empty when the event does not change the phase (the caller keeps the previous phase).

type FileChange

type FileChange struct {
	Path string `json:"path,omitempty"`
	Kind string `json:"kind,omitempty"`
}

FileChange describes one edited path inside a file_change item.

type Item

type Item struct {
	ID               string          `json:"id,omitempty"`
	Type             string          `json:"type,omitempty"`
	Text             string          `json:"text,omitempty"`
	Command          string          `json:"command,omitempty"`
	AggregatedOutput string          `json:"aggregated_output,omitempty"`
	ExitCode         *int            `json:"exit_code,omitempty"`
	Status           string          `json:"status,omitempty"`
	Server           string          `json:"server,omitempty"`
	Tool             string          `json:"tool,omitempty"`
	Query            string          `json:"query,omitempty"`
	Review           string          `json:"review,omitempty"`
	Changes          []FileChange    `json:"changes,omitempty"`
	Summary          json.RawMessage `json:"summary,omitempty"`
}

Item is the payload of item.started / item.updated / item.completed events.

type Provider

type Provider struct{}

Provider drives the OpenAI Codex CLI.

func (Provider) Analyze

func (Provider) Analyze(args []string, resultFile string, allowJSON bool) agent.Analysis

Analyze injects the `exec --json` / `--output-last-message` flags that make a codex run observable. See the package-level Analyze.

func (Provider) BinCandidates

func (Provider) BinCandidates() []string

func (Provider) BinEnv

func (Provider) BinEnv() string

func (Provider) Doctor

func (Provider) Doctor(bin string, run agent.RunFunc) agent.DoctorReport

Doctor checks that codex is installed and responding via `codex --version` and `codex doctor --json` (which covers install/config/auth/runtime health).

func (Provider) Name

func (Provider) Name() string

func (Provider) ParseLine

func (Provider) ParseLine(line string) (agent.Event, bool)

ParseLine normalizes a `codex exec --json` line into an agent.Event: it maps the phase/summary via Describe, tracks command/tool items for the watchdog, captures the final agent_message (or review payload) as the result, and flags error/turn.failed lines as failures.

func (Provider) ReviewArgs

func (Provider) ReviewArgs(spec agent.ReviewSpec) ([]string, error)

ReviewArgs builds a native `codex exec review` invocation; codex has a purpose-built reviewer, so we use it rather than a constructed prompt.