agentsmd

README

agentsmd

The AGENTS.md convention for Go agents: the instruction files that apply at a path, found from its directory up to a root, one per directory, nearest last, and rendered into the text a product puts in its instructions. The module imports the standard library alone.

res, err := agentsmd.Chain(cwd, agentsmd.Options{
	Names:  []string{"AGENTS.override.md", "AGENTS.md"},
	Root:   repoRoot,
	Extra:  []string{filepath.Join(home, ".dex", "AGENTS.md")},
	Budget: 32 << 10,
})
if err != nil {
	return err
}
for _, o := range res.Omitted {
	log.Printf("%s (%d bytes): %s", o.Path, o.Size, o.Reason) // shadowed or over budget
}
cfg.Instructions = agentsmd.Render(res.Files)

Chain walks from the path's directory to Root, takes in each directory the first of Names that exists, and returns the files farthest first and nearest last, then Extra, so that later text refines earlier text. Budget caps the total: the first file that would exceed it ends the chain, nothing is cut short, and running out is not an error. Every file found and left out, shadowed by a preferred name or over budget, is in Result.Omitted with its size, so a product can tell the user and a session can record what the model was not given as well as what it was.

Render wraps the files as pi renders <project_context>: one <project_instructions path="..."> per file, in order.

The package is about a repository checkout on the local file system. It does not expand imports inside files, know any file name specially, or fetch anything; a product with a remote checkout hands its files to Render itself.

Development

make check    # gofmt, tidy, vet, deps, staticcheck, govulncheck, race tests

The fixture tree is testdata/tree; the golden render is testdata/golden/render.txt, regenerated with go test . -update.

Documentation

Overview

Package agentsmd finds and renders the instruction files of the AGENTS.md convention: the files that apply at a path are the ones in its directory and every ancestor, one per directory, and the nearest takes precedence.

Chain collects them farthest first and nearest last, so that when a product includes every file, later text refines earlier text, and says which files it found and left out, so a product can record or show exactly what the model was given and what it was not. Render wraps the files the way pi renders project context, one project_instructions element per file inside project_context. The package imports the standard library alone.

Index

• Constants
• Variables
• func Render(files []File) string
• type File
• type Omitted
• type Options
• type Reason
  • func (r Reason) String() string
• type Result
  • func Chain(path string, opts Options) (Result, error)

Constants

const DefaultMaxBytes = 1 << 20

DefaultMaxBytes is the size above which a file is an error.

Variables

var DefaultNames = []string{"AGENTS.md"}

DefaultNames is the file name Chain looks for when Options.Names is empty.

var ErrTooLarge = errors.New("agentsmd: file exceeds size limit")

ErrTooLarge is wrapped in the error of a file over MaxBytes.

Functions

func Render

func Render(files []File) string

Render wraps the files as pi does: one project_instructions element per file, with its path as the attribute, inside project_context, in order. No files render as the empty string.

Types

type File

type File struct {
	// Path is absolute.
	Path string
	// Content is the file's bytes as a string.
	Content string
}

File is one instruction file, read verbatim.

type Omitted

type Omitted struct {
	// Path is absolute.
	Path string
	// Size is the file's size in bytes.
	Size int64
	// Reason says why the file is not in [Result.Files].
	Reason Reason
	// By is the path of the file that took this one's place, for
	// [Shadowed]; "" otherwise.
	By string
}

Omitted is one file Chain found and left out.

type Options

type Options struct {
	// Names are the file names looked for in each directory, in order
	// of preference: the first one found is that directory's file and
	// the rest are not read, so a product can let AGENTS.override.md
	// shadow AGENTS.md, or CLAUDE.md stand in where AGENTS.md is
	// absent, as Codex reads them. Empty means [DefaultNames].
	Names []string
	// Root is the directory the walk stops after. Empty means the
	// file system root. A path outside Root is an error.
	Root string
	// Extra are explicit paths appended after the chain, in order,
	// such as a file in the user's home directory. Missing ones are
	// skipped.
	Extra []string
	// MaxBytes bounds one file; zero means [DefaultMaxBytes]. A larger
	// file is an error, because a truncated instruction file would
	// silently change what the model is told.
	MaxBytes int64
	// Budget bounds the total bytes of every file returned. The first
	// file that would take the total over it, and every file after
	// it, is left out and reported in [Result.Omitted], and Chain
	// returns what fits without error, so a large file deep in a tree
	// degrades the prompt rather than failing the run. No file is cut
	// short. Zero means no budget.
	Budget int64
}

Options configure Chain.

type Reason

type Reason int

Reason is why Chain left a file out.

const (
	// OverBudget: the file, or one before it, would have taken the
	// total over Options.Budget, and the chain ends at the first such
	// file.
	OverBudget Reason = iota
	// Shadowed: an earlier name in Options.Names exists in the same
	// directory and stands for it.
	Shadowed
)

func (Reason) String

func (r Reason) String() string

String returns "over budget" or "shadowed".

type Result

type Result struct {
	// Files are the instruction files to include, farthest first and
	// nearest last, then Extra.
	Files []File
	// Omitted are the files Chain found and did not include, in the
	// order it met them.
	Omitted []Omitted
}

Result is what Chain found: the files that apply, in order, and the files it saw and left out, so a product can record or show exactly what the model was given and what it was not.

func Chain

func Chain(path string, opts Options) (Result, error)

Chain returns the instruction files that apply at path: in path's directory and each of its ancestors up to opts.Root, the first file of opts.Names that exists, farthest first and nearest last, followed by opts.Extra in order, within opts.Budget. A file found and not included, because a preferred name shadows it or the budget is spent, is in Result.Omitted; only a file that would be included is read, and only such a file over opts.MaxBytes is an error. path may be a directory, an existing file, or a file about to be created, whose directory is then the start.