codex

Documentation

Overview

Package codex provides hook-based capture for OpenAI Codex sessions.

Hooks are configured in <repo>/.codex/hooks.json. Codex surfaces that do not emit project hooks are outside this provider's capture path.

Index

• type Provider
  • func New() *Provider
  • func (p *Provider) AreHooksInstalled(ctx context.Context, repoRoot string) bool
  • func (p *Provider) BuildHookEvents(ctx context.Context, event *hooks.Event, bs api.BlobPutter) ([]broker.RawEvent, error)
  • func (p *Provider) DisplayName() string
  • func (p *Provider) HookBinary(ctx context.Context, repoRoot string) (string, error)
  • func (p *Provider) InstallHooks(ctx context.Context, repoRoot string, binaryPath string) (int, error)
  • func (p *Provider) IsAvailable() bool
  • func (p *Provider) Name() string
  • func (p *Provider) ParseHookEvent(ctx context.Context, hookName string, stdin io.Reader) (*hooks.Event, error)
  • func (p *Provider) ReadFromOffset(ctx context.Context, transcriptRef string, offset int, bs api.BlobPutter) ([]broker.RawEvent, int, error)
  • func (p *Provider) ShouldCapture(ctx context.Context, payload []byte, activeRepos []broker.RegisteredRepo) (bool, error)
  • func (p *Provider) TranscriptOffset(ctx context.Context, transcriptRef string) (int, error)
  • func (p *Provider) UninstallHooks(ctx context.Context, repoRoot string) error

Types

type Provider

type Provider struct{}

Provider implements hooks.HookProvider for OpenAI Codex.

func New

func New() *Provider

New returns a Codex hook provider.

func (*Provider) AreHooksInstalled

func (p *Provider) AreHooksInstalled(ctx context.Context, repoRoot string) bool

AreHooksInstalled reports whether the project file contains Semantica hooks.

func (*Provider) BuildHookEvents

func (p *Provider) BuildHookEvents(ctx context.Context, event *hooks.Event, bs api.BlobPutter) ([]broker.RawEvent, error)

BuildHookEvents converts direct Codex hooks into stored events.

func (*Provider) DisplayName

func (p *Provider) DisplayName() string

func (*Provider) HookBinary

func (p *Provider) HookBinary(ctx context.Context, repoRoot string) (string, error)

HookBinary returns the binary used by an installed Semantica hook.

func (*Provider) InstallHooks

func (p *Provider) InstallHooks(ctx context.Context, repoRoot string, binaryPath string) (int, error)

InstallHooks merges repo-local hooks and enables Codex's global hook gate. Existing hooks are preserved. If repository publication fails after the gate changes, the installer attempts to restore the prior global config.

func (*Provider) IsAvailable

func (p *Provider) IsAvailable() bool

IsAvailable reports whether Codex appears to be installed.

func (*Provider) Name

func (p *Provider) Name() string

func (*Provider) ParseHookEvent

func (p *Provider) ParseHookEvent(ctx context.Context, hookName string, stdin io.Reader) (*hooks.Event, error)

ParseHookEvent converts Codex hook input to a normalized event.

Hook event mapping:

• session_start -> SessionOpened (lifecycle no-op in the dispatcher)
• user_prompt_submit -> PromptSubmitted
• pre_tool_use -> ToolStepStarted (Bash only; pre-execution snapshot)
• post_tool_use -> ToolStepCompleted
• stop -> AgentCompleted

Codex Stop ends a turn, not the session.

func (*Provider) ReadFromOffset

func (p *Provider) ReadFromOffset(ctx context.Context, transcriptRef string, offset int, bs api.BlobPutter) ([]broker.RawEvent, int, error)

ReadFromOffset is a no-op because this provider relies on hook payloads.

func (*Provider) ShouldCapture

func (p *Provider) ShouldCapture(ctx context.Context, payload []byte, activeRepos []broker.RegisteredRepo) (bool, error)

ShouldCapture reports whether the hook belongs to an active repository.

func (*Provider) TranscriptOffset

func (p *Provider) TranscriptOffset(ctx context.Context, transcriptRef string) (int, error)

TranscriptOffset returns zero because Codex capture does not replay files.

func (*Provider) UninstallHooks

func (p *Provider) UninstallHooks(ctx context.Context, repoRoot string) error

UninstallHooks removes Semantica entries from the project hook file. Global hooks, the feature flag, trust state, and unrelated entries remain.