Harness for Codex
A repository-level harness that gives OpenAI Codex, Claude Code, and Cursor shared agent instructions and standard scripts, so every AI-assisted task starts from a predictable baseline.
- Source repo
- ganimjeong/Harness-for-codex
- Stars
- ★ 51
- Last updated
- 5mo ago
- License
- MIT
- Primary language
- Shell
- FA score
- 54/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer bootstrapping a new repository for Codex work who wants ready agent instructions and standard commands from day one
- Not a fit if
- Users expecting a standalone AI product that writes code for them
- Teams wanting a harness that ships an actual language stack, tests, or CI implementation
- Workflows that need a GUI or a hosted service
- Maintenance
- Commits in the last 6 monthslast commit 2026-05-30latest release v0.1.0 (2026-05-30)
- Source review
- 54/100 · Major gaps
What does this agent do, and when should you use it?
Harness for Codex is a language-agnostic repository scaffold that standardizes how coding agents operate on your codebase. It centers shared agent rules in AGENTS.md and bridges Claude Code via a CLAUDE.md that imports the same guidance, so Codex, Claude Code, and Cursor all follow one contract. The repository ships six standard automation entrypoints—scripts/bootstrap, check, test, eval, doctor, and hooks—mirrored as justfile commands, with harness.yml recording canonical command names and task-loop stages. The documented workflow pairs task briefs (tasks/TEMPLATE.md) and durable decision records (docs/decisions.md) with a final scripts/check before handoff. An optional dev container runs scripts/bootstrap after creation, but local development works without Docker. It implements no AI agent and contains no language stack itself—it is a process contract that agents read and execute.
Once adopted, the repository exposes a fixed set of entrypoints to coding agents: scripts/bootstrap prepares dependencies when a known stack is present; scripts/check runs formatting, lint, type, and test checks when available; scripts/test runs the test suite; scripts/eval acts as a handoff gate by running doctor, bootstrap, and check in sequence; scripts/doctor prints repository and tooling readiness; scripts/hooks installs optional local hooks via pre-commit. OpenAI Codex reads AGENTS.md directly, Claude Code reads CLAUDE.md which imports the same instructions, and Cursor can use AGENTS.md as shared project guidance. harness.yml records canonical command names, expected documentation files, and task-loop stages, and must stay aligned with AGENTS.md and the scripts. Users write task briefs from tasks/TEMPLATE.md, record durable decisions in docs/decisions.md, and run scripts/check before finishing.
- A developer bootstrapping a new repository for Codex work who wants ready agent instructions and standard commands from day one
- Teams using OpenAI Codex, Claude Code, and Cursor side by side who need one shared rule set to prevent behavior drift across tools
- Automation agents that need stable setup, check, test, and handoff-evaluation entrypoints for unattended runs
- Maintainers who want project decisions and task briefs kept in predictable locations that future agents can read
- Empty or early-stage repositories that want to adopt any language stack later without replacing the harness contract
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Config files
.devcontainer/devcontainer.json- Install notes cover
- Docker
How do you install or deploy this agent?
There is no separate install step: clone or copy the repository as the base of your project.
bash
git clone https://github.com/ganimjeong/Harness-for-codex.git your-project
cd your-projectOptional: for local hooks, run scripts/hooks to install via pre-commit; for a containerized environment, use the bundled .devcontainer/devcontainer.json (it runs scripts/bootstrap after creation). Local development works without Docker.
How do you use this agent?
For a first run, check readiness and verify the baseline:
bash
scripts/bootstrap
scripts/check
scripts/doctorIn day-to-day work: write a task brief in tasks/ using TEMPLATE.md when context is needed; implement your changes; record durable decisions in docs/decisions.md; run scripts/check before finishing. For the full pre-handoff evaluation:
bash
scripts/evalIf you use just, the same commands are exposed as:
bash
just check
just evalWhat are this agent's strengths and limitations?
- One AGENTS.md covers Codex, Claude Code, and Cursor, with a CLAUDE.md bridge so rules are not duplicated across tools
- The layered doctor/bootstrap/check/eval design makes eval a complete handoff gate suitable for unattended agent workflows
- harness.yml explicitly records canonical commands and task-loop stages, making the contract auditable and alignable
- Language-agnostic: any language stack can be added later without replacing the harness contract
- The repository contains no language stack or test implementation itself—the scripts are safe defaults for empty repos that you must extend
- Its value depends on your agent (Codex/Claude Code/Cursor) actually honoring the AGENTS.md conventions; there is no enforcement mechanism
- Optional hooks depend on pre-commit and the container path on Docker, both extra environment requirements
- No additional repository guidance is cached; adaptation details must be inferred from the README and scripts
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Harness for Codex This agent | 54 · Major gaps | Agent plugin / skillFree | ★ 51 | 5mo ago | Shell | Codex · Claude Code |
| CoCo Super Intelligence | 64 · Some gaps | Agent plugin / skillFree + model costs | ★ 327 | today | Python | Codex · Claude Code |
| Self-Learning Skills | 54 · Major gaps | Agent plugin / skillFree + model costs | ★ 925 | 2mo ago | — | Codex · Claude Code |
| AIWG | 77 · Good | CLIFree + model costs | ★ 232 | today | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
AGENTS.md asks agents to keep changes scoped and preserve user changes; CI declares only contents: read, supporting a partial least-privilege assessment. Deductions: there is no explicit confirmation rule for high-impact actions or credential-handling guidance. README mentions bootstrap, hooks, and a devcontainer, but their scripts and configurations are not supplied, so data flows, external effects, dependency security, and rollback cannot be verified. The MIT license names Ajin Jeong, but publisher identity is unverified and no clear maintainer or update path is shown.
README, AGENTS.md, and the CI workflow describe the standard entrypoints and evaluation sequence consistently, supporting full marks. Deductions: the actual bootstrap/check/test scripts are not supplied, so missing-dependency behavior and error messages cannot be assessed; the GitHub Action uses the @v4 tag rather than an immutable version pin.
The README names new repositories, cross-agent workflows, and later addition of language stacks as use cases; AGENTS.md also describes the layout and task loop. Deductions: capability boundaries are general, with little detail on unsuitable scenarios, trigger rules, or supported environments. The devcontainer is labeled optional, but behavior in other environments is not shown.
README, AGENTS.md, CLAUDE.md, and the layout description provide a clear information architecture; command names are consistent, and quick-start, workflow, and just examples are present. The MIT license text is complete. Deductions: setup guidance is brief, FAQ and limitations coverage is thin, the supplied sample has no version or change history, and maintainer responsibility or an update path is not specified.
Standard entrypoints, a task template, and decision records could help teams align agent workflows, and the commands and their intended uses are easy to follow. Deductions: the evidence describes the framework but does not include its scripts, so actual coverage and maintenance cost cannot be confirmed; the claimed value has no outcome evidence in the supplied files.
Descriptions of commands and workflow can be compared across the README, AGENTS.md, and CI workflow; the license and CI permission are directly evidenced. Deductions: several feature claims lack corresponding script or configuration samples, and the documentation does not consistently distinguish implemented behavior from intended use. Conclusions are limited to the supplied files.
- The supplied material omits the scripts, hooks, devcontainer configuration, and harness.yml mentioned by the README, so their actual permissions, side effects, dependencies, and error handling remain unverified.
- CI uses the actions/checkout@v4 tag; the supplied material does not describe a dependency update or version-pinning policy.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Initial public release of the Codex harness. Includes AGENTS.md instructions, Claude Code bridge, standard bootstrap/check/test/eval scripts, CI, hooks, task template, workflow docs, MIT license,and public contribution templates.View on GitHub ↗
FAQ
Is it free? Does it need API keys?
Do I need Docker?
Which AI tools does it support?
What does scripts/check do in an empty repository?
How does it keep agent behavior consistent?
Is Harness for Codex open source?
Is Harness for Codex safe to use?
Is Harness for Codex still maintained?
Who makes Harness for Codex?
Thanks — we use this to improve the page.