CodexAgentLedger is a Codex compatible AgentOps repo standard using AGENTS.md,

• **Markdown state (STATUS.md, TASKS.md) and a JSON run ledger (.agent/runs/*.json)
• **backed by a Makefile CI interface (make ci).

Why this exists

This standard gives agents a reliable way to work in a codebase without chaos.

It defines

• A single, human readable source of truth for what is happening
  (STATUS.md, TASKS.md)

• A machine readable audit trail of what actually happened
  (.agent/runs/*.json, .agent/index.json)

• A consistent tooling API so agents run the same checks every time
  (Makefile targets like make ci)

• A contract that makes work repeatable across repos and teams
  (AGENTS.md)

Engineers need it because it prevents two common failure modes

• Agents make changes but nobody can quickly tell what changed, why, and whether it passed checks
• Work cannot be reliably resumed, reviewed, or automated because state and logs are scattered

With this in place, any agent, human, or CI system can pick up the repo, see current intent in one screen, and verify or replay work through structured run records and context.

Agent Repo Standard (Markdown State + JSON Run Ledger)

This repo is a drop-in template for running coding agents (Codex-style or any agent) in a consistent, auditable way.

What you get

Human readable state (Markdown)

• STATUS.md, one-page snapshot of what is happening now
• TASKS.md, backlog, doing, done, with stable task IDs
• WORKLOG.md, optional daily notes

Automation first audit trail (JSON)

• .agent/runs/*.json, one file per agent run
• .agent/index.json, rollup index for dashboards and tooling

Agent contract

• AGENTS.md defines rules for agents, definition of done, and how to update files
• Makefile acts as the repo's tooling API for agents (fmt, lint, test, ci)

Quick start

1. Copy these files into an existing repo (or start from this template).
2. Edit AGENTS.md to match your stack (Python, Node, Go, etc.).
3. Customize the Makefile commands if needed.
4. When an agent completes a task:
   • update TASKS.md and STATUS.md
   • write a run record in .agent/runs/
   • run make ci (or document why it could not be run)

Files

• AGENTS.md, agent operating rules and definition of done
• SPEC.md, the actual spec for Markdown files and JSON run records
• STATUS.md, current snapshot
• TASKS.md, tasks and completion tracking
• .agent/, machine readable run ledger plus templates
• scripts/, helper scripts for maintaining .agent/index.json

Example workflow

• Pick a task in TASKS.md (example: T-001)
• Make changes
• Run make ci
• Record the run:
  • create .agent/runs/<timestamp>_T-001.json
  • reference that file in the task entry
• Mark the task done in TASKS.md
• Update STATUS.md (Last update and Now)

License

MIT, see LICENSE.

Relationship to OpenAI Codex and agent standards

This template is designed to work well with OpenAI's Codex style workflows, but it is framework-agnostic.

• AGENTS.md is used as the primary agent instructions contract, aligned with Codex guidance that Codex reads AGENTS.md before doing work.
• Makefile targets act as a stable interface for agents (preferred over ad hoc commands).
• Optional: If you use Codex CLI or Codex IDE, you can connect tools and context via MCP (Model Context Protocol).

What is official vs local here

Official style pieces

• AGENTS.md as the agent instruction file
• MCP as a tool connection protocol (optional)

Local, practical additions in this repo

• STATUS.md and TASKS.md as human readable state
• .agent/runs/*.json as a project-local run ledger for your own automation and dashboards

If you also use the OpenAI Agents SDK, its built-in tracing can complement the .agent/ run ledger for debugging and observability.