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
- ★ 48
- Last updated
- 4mo ago
- License
- MIT
- Primary language
- Shell
- FA score
- 47/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
- Source review
- 47/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
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. (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 | 47 · Major gaps | Agent plugin / skillFree | ★ 48 | 4mo ago | Shell | Codex · Claude Code |
| CoCo Super Intelligence | 69 · Some gaps | Agent plugin / skillFree + model costs | ★ 538 | today | HTML | Codex · Claude Code |
| Self-Learning Skills | 56 · Major gaps | Agent plugin / skillFree + model costs | ★ 959 | 13d ago | — | Codex · Claude Code |
| Loop Library: Reusable AI Agent Workflows | 61 · Some gaps | Agent plugin / skillFree | ★ 3.2k | 16d ago | JavaScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence is limited to README, LICENSE, and one CI workflow. CI follows least privilege (contents: read, timeout, concurrency cancellation), which is positive, but the actual sources of scripts/bootstrap, scripts/check, and pre-commit hooks are absent, so least privilege, sensitive data handling, and rollback can only be scored 1 as unverified claims. No malicious behavior found; no red line.
README claims the scripts are 'safe defaults for an empty repository', but their implementations are not visible; failure messages, dependency-missing behavior, and self-consistency between docs and code cannot be verified — 1 across the board.
Audience and scenarios are reasonably clear (Codex/Claude/Cursor, language-agnostic, optional devcontainer, justfile) — 2; capability boundaries and trigger precision are handled only by a passing 'extend as the project grows' remark — 1.
Directory layout, canonical command names, and install instructions are well described — 2; full MIT license text present — 3; but no changelog/versioning, no FAQ/examples, no known-limitations doc, and no stated maintenance/update path — 1 each.
Unified entrypoints, task templates, and decision logs offer real marginal value for multi-agent workflows; usability is adequate — 2 each. The repo is fundamentally a scaffold, and benefits depend on downstream adoption; higher scores are not warranted by the evidence.
README references harness.yml, AGENTS.md, scripts/, none of which are in the provided evidence, so cross-source corroboration is impossible — 1. Claims are mostly factual rather than marketing — 2. Key command behaviors are not traceable to source — 1.
- Review is based only on static README/LICENSE/CI evidence; actual scripts and AGENTS.md content were not provided, so core safety properties (permissions, side effects, rollback) are unverified.
- Before use, manually review scripts/bootstrap, scripts/check, scripts/hooks, and harness.yml to confirm they do not fetch or execute untrusted network content or modify files outside the repository.
- No releases, changelog, or maintenance commitment is documented; adopt with a revision-pinning strategy.
- Publisher is unverified and identity unknown; independently verify provenance before production use.