Harness-for-codex is a language-agnostic repository scaffold for keeping AI-assisted development workflows consistent. It targets OpenAI Codex, coding agents, Claude Code, and Cursor, providing persistent AGENTS.md instructions, standard automation entry points, task templates, verification scripts, and lightweight workflow documentation for agent-driven software work.
Purpose: You can use it as a Codex harness, an AGENTS.md template, or a reusable coding agent project scaffold so that every subsequent task starts from a predictable baseline:
- Centralized agent instructions via AGENTS.md
- One bootstrap command
- One check command
- One test command
- One full evaluation command
- Optional hooks and devcontainer metadata
- Lightweight documentation for recording decisions and tasks
Use cases:
- Start a new repository with Codex-ready agent instructions.
- Standardize coding agent workflows across OpenAI Codex, Claude Code, and Cursor.
- Give automation agents stable setup, check, test, and handoff evaluation commands.
- Keep project decisions and task briefs in predictable locations.
- Add a language stack later without replacing the harness contract.
Main offerings:
- AGENTS.md: repository-local operating instructions for Codex and compatible agents.
- CLAUDE.md: Claude Code bridge file that imports the shared AGENTS.md guidance.
- scripts/bootstrap: dependency preparation when a known stack is present.
- scripts/check: runs lint, formatting, type, and test checks when available.
- scripts/test: focused test suite entry point.
- scripts/eval: complete handoff verification via doctor, bootstrap, and check.
- tasks/TEMPLATE.md: task brief template for work that needs persistent context.
- docs/decisions.md: persistent decisions that future agents should preserve.
Usage:
- When work needs context, write a task brief in tasks/.
- Implement changes in the relevant project files.
- Record persistent decisions in docs/decisions.md.
- Run scripts/check before finishing.
Automation entry points:
- scripts/bootstrap: installs or prepares dependencies when a known stack is present.
- scripts/check: runs formatting, lint, type checks, and tests when available.
- scripts/test: runs the test suite when available.
- scripts/eval: runs doctor, bootstrap, and check as a handoff gate.
- scripts/doctor: prints repository and tool readiness status.
- scripts/hooks: installs optional local hooks via pre-commit.
- If using just, the same commands are exposed in the justfile. These scripts are safe defaults for empty or early-stage repositories and can expand as the project grows.
Compatible agents:
- OpenAI Codex reads AGENTS.md for repository instructions.
- Cursor can use AGENTS.md as shared project guidance.
- Claude Code reads CLAUDE.md, which imports the same shared instructions. Keep shared rules in AGENTS.md so agent behavior stays consistent across tools. Add tool-specific notes only when a tool needs a different bridge.
Harness metadata: harness.yml records canonical command names, expected documentation files, and task loop stages. Keep it consistent with AGENTS.md and this repository's scripts.
Optional environment: The repository includes a minimal dev container that runs scripts/bootstrap after creation. It is optional; local development can proceed without Docker.
