codex

Documentation

Overview

Package codex implements the Codex (AGENTS.md) aggregator harness adapter.

Codex consumes a single project-root AGENTS.md document. Renderer.Render produces a per-skill "fragment" — a section wrapped in begin/end markers. Adapter.Aggregate concatenates the fragments into one AGENTS.md, packs them under the 32 KiB project_doc_max_bytes budget, and prepends a truncation manifest when parts were dropped.

Index

• Constants
• type Adapter
  • func NewAdapter(r *Renderer, p budget.Packer, w fsutil.Writer) *Adapter
  • func NewAdapterWithReader(r *Renderer, p budget.Packer, w fsutil.Writer, f FileReader) *Adapter
  • func (a *Adapter) Aggregate(_ context.Context, parts []adept.RenderOutput, budgetB int) ([]adept.RenderOutput, error)
  • func (a *Adapter) Detect(projectRoot string) (bool, error)
  • func (a *Adapter) Import(_ context.Context, projectRoot string) ([]adept.ImportedSkill, error)
  • func (a *Adapter) Renderer() adept.Renderer
  • func (a *Adapter) Spec() adept.HarnessSpec
  • func (a *Adapter) Validate(projectRoot string, expected []adept.RenderOutput) (adept.DriftReport, error)
• type FileReader
• type Renderer
  • func New() *Renderer
  • func (r *Renderer) Render(_ context.Context, in adept.RenderInput) (adept.RenderOutput, error)

Constants

const ManifestOverheadB = 512

ManifestOverheadB reserves bytes for the truncation manifest comment when the packer needs to drop skills. Keep generous enough for plausible ID lists.

const OutputFile = "AGENTS.md"

OutputFile is the on-disk file Codex reads from a project.

const SizeBudgetB = 32 * 1024

SizeBudgetB is Codex's project_doc_max_bytes default.

Types

type Adapter

type Adapter struct {
	// contains filtered or unexported fields
}

Adapter implements adept.HarnessAdapter for Codex.

Adapter is the Aggregate orchestrator; it does NOT itself write to disk. The outer apply/sync command takes the []RenderOutput we return and hands it to the fsutil.Writer at materialization time. The Writer is wired here so future variants of the adapter that perform their own writes can use it; reads (Detect/Validate) go through FileReader.

func NewAdapter

func NewAdapter(r *Renderer, p budget.Packer, w fsutil.Writer) *Adapter

NewAdapter builds a Codex adapter. All collaborators are injected; no globals. A default os-backed FileReader is used.

func NewAdapterWithReader

func NewAdapterWithReader(r *Renderer, p budget.Packer, w fsutil.Writer, f FileReader) *Adapter

NewAdapterWithReader is a test seam allowing a custom FileReader.

func (*Adapter) Aggregate

func (a *Adapter) Aggregate(_ context.Context, parts []adept.RenderOutput, budgetB int) ([]adept.RenderOutput, error)

Aggregate concatenates per-skill fragments into a single AGENTS.md output. The budgetB parameter overrides the spec default when non-zero; pass 0 to use the default (32 KiB).

func (*Adapter) Detect

func (a *Adapter) Detect(projectRoot string) (bool, error)

Detect returns true if either a project AGENTS.md exists or a .codex/ directory is present at the project root.

func (*Adapter) Import

func (a *Adapter) Import(_ context.Context, projectRoot string) ([]adept.ImportedSkill, error)

Import parses <project>/AGENTS.md. If the file was produced by adept the `adeptability:begin/end` markers split it into one canonical skill per section. If no markers are present we synthesize a single skill named `agents` with the entire file as body — that lets users adopt a hand-written AGENTS.md into adept's canonical layout.

func (*Adapter) Renderer

func (a *Adapter) Renderer() adept.Renderer

Renderer returns the per-skill fragment renderer.

func (*Adapter) Spec

func (a *Adapter) Spec() adept.HarnessSpec

Spec returns the static description used by the harness registry.

func (*Adapter) Validate

func (a *Adapter) Validate(projectRoot string, expected []adept.RenderOutput) (adept.DriftReport, error)

Validate compares expected aggregated output to disk and reports drift. The DriftReport carries a single entry keyed by "codex" — the whole harness is either Synced, Drifted, or Missing.

type FileReader

type FileReader interface {
	// ReadFile returns the bytes at path or fs.ErrNotExist if absent.
	ReadFile(path string) ([]byte, error)
	// Exists reports whether path exists on disk.
	Exists(path string) (bool, error)
}

FileReader exposes the minimal read surface needed by Detect/Validate. The Writer interface in internal/fsutil is write-only; reads use this dedicated seam so tests can inject in-memory fakes without depending on any disk activity.

type Renderer

type Renderer struct{}

Renderer produces a single-skill fragment for an aggregated AGENTS.md.

The fragment is wrapped in begin/end markers so the aggregator can concatenate parts deterministically and so future Detect logic can locate adept-owned sections.

func New

func New() *Renderer

New returns a Codex renderer with default behavior.

func (*Renderer) Render

func (r *Renderer) Render(_ context.Context, in adept.RenderInput) (adept.RenderOutput, error)

Render emits the per-skill fragment. The Path is the aggregated file name, not a per-skill output — the Adapter merges fragments by Path.