codex

Documentation

Overview

Package codex implements testagent's "codex" subcommand — the v1 fake for OpenAI's Codex CLI. Vendor-specific knobs (codex-shaped flags, the `~/.codex/config.toml` loader, AGENTS.md surfacing) live here; the shared engine loop in internal/engine drives the actual session.

Index

• func NewCommand(rf *rootflags.Flags) *cobra.Command
• type Config
• type HookEntry
• type HooksTable
• type MCPServer
• type MatcherGroup

Functions

func NewCommand

func NewCommand(rf *rootflags.Flags) *cobra.Command

NewCommand returns the "codex" subcommand wired against the given root flags. The bare `testagent codex` invocation drops into an interactive session; `codex resume <SESSION_ID>` and `codex exec <prompt>` are child subcommands.

Types

type Config

type Config struct {
	MCPServers map[string]MCPServer `toml:"mcp_servers"`
	Hooks      HooksTable           `toml:"hooks"`
}

Config mirrors the subset of `~/.codex/config.toml` the MVP consumes. Unknown TOML keys are tolerated — the loader uses BurntSushi/toml's default decoder, which silently ignores fields that don't appear here.

type HookEntry

type HookEntry struct {
	Type    string `toml:"type"`
	Command string `toml:"command,omitempty"`
	Prompt  string `toml:"prompt,omitempty"`
	Agent   string `toml:"agent,omitempty"`
	Timeout int    `toml:"timeout,omitempty"`
	Async   bool   `toml:"async,omitempty"`
}

HookEntry is one concrete hook handler under a MatcherGroup. Type discriminates between codex's three handler shapes:

• "command": run a shell command (the only type testagent fires today)
• "prompt": inject a prompt (accepted-but-ignored; tracked in a follow-up)
• "agent": delegate to a sub-agent (accepted-but-ignored)

All type-specific fields live on this struct as omitempty; the runner reads only the ones relevant to Type.

type HooksTable

type HooksTable map[string][]MatcherGroup

HooksTable maps a codex hook event name (e.g. "SessionStart") to a list of MatcherGroups. Each group filters by `matcher` (currently unused — accepted for forward compatibility) and contains a list of concrete hook entries. Wired through codexhooks.Runner in cmd/codex.runInteractive via matchersFromConfig.

Mirrors upstream codex's schema:

[[hooks.SessionStart]]
matcher = "..."
[[hooks.SessionStart.hooks]]
type = "command"
command = "..."

type MCPServer

type MCPServer struct {
	Type    string            `toml:"type"`
	Command string            `toml:"command"`
	Args    []string          `toml:"args"`
	Env     map[string]string `toml:"env"`
	URL     string            `toml:"url"`
	Headers map[string]string `toml:"headers"`
}

MCPServer is one entry under [mcp_servers.<name>] in the codex TOML. Codex servers can use stdio or HTTP transports; we capture both shapes even though MVP only consumes [mcp_servers] presence.

type MatcherGroup

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

MatcherGroup is one entry under a `[hooks.<event>]` array. The matcher pattern (when codex eventually wires it) selects which events the contained hooks respond to; for the MVP we run every hook unconditionally.