⚙️ OpenHarness For Codex

Let your Agent act as the Product Owner. Let Codex write the code. You just describe what you want.

"You are not the developer. You are the architect. Codex is your hands."

OpenHarness For Codex is a specialized variant of the OpenHarness framework designed for AI-driven software development. It turns your Agent into a Product Owner + Verifier, while delegating all code writing to Codex CLI. The result is a fully autonomous, multi-round development loop that runs 24/7 until your project passes validation.

---

🤔 Why OpenHarness For Codex?

Most "AI coding" workflows look like this: you ask the AI to write code, it looks plausible, you run it, it breaks, you paste the error back, repeat forever — manually.

OpenHarness For Codex automates this entire loop:

Capability	Without OpenHarness For Codex	With OpenHarness For Codex
Multi-round iteration	Manual copy-paste	Fully automated
Error diagnosis	You read the logs	Agent extracts & feeds to Codex
Service validation	You run it manually	harness_service.py + harness_eval.py
Cross-session recovery	Starts from scratch	heartbeat.md breakpoint resume
Completion standard	Subjective ("looks good")	Machine-verifiable eval report

---

🏛️ Architecture

The framework enforces a strict two-role separation:

Role	Executor	Responsibilities	Hard Constraint
Requester + Verifier	Your Agent	Read requirements, design architecture, write docs, construct Prompts, start/stop services, check logs, evaluate quality, drive iterations	Never write business code directly
Executor (Hands)	Codex CLI	Write, modify, and refactor code based on Prompts	Never modify framework state files

The Automated Development Loop

User describes project in mission.md
         ↓
Agent reads requirements → writes tech_spec.md
         ↓
Agent constructs Prompt → calls Codex CLI (full-auto)
         ↓
Codex writes code into project_src/
         ↓
harness_service.py: install deps + start service
         ↓
harness_eval.py: HTTP health check + log analysis → eval_report.json
         ↓
Agent reads report → writes iteration_N.md
         ↓
  [FAIL] → Agent extracts error logs → constructs fix Prompt → back to Codex
  [PASS after N rounds] → package deliverables → mission_complete

Workspace Structure

After initialization, your project workspace looks like:

my-project/
├── mission.md           ← 📜 Your requirements (read-only "constitution")
├── playbook.md          ← 🗺️ Agent's execution playbook
├── eval_criteria.md     ← 🔍 Validation criteria
├── heartbeat.md         ← 💓 Cross-session state (Agent reads/writes)
├── progress.md          ← 📊 Execution history log
├── project_src/         ← 💻 Code written by Codex
├── reports/             ← 📝 Agent's technical docs and iteration reports
│   ├── tech_spec.md
│   ├── iteration_1.md
│   └── iteration_2.md
├── logs/                ← 🗂️ Service logs, eval reports, Codex prompts
│   ├── service.log
│   ├── eval_report.json
│   └── codex_prompt_iter1.txt
├── deliverables/        ← 📦 Final packaged output
└── scripts/             ← ⚙️ Framework scripts (auto-copied on init)
    ├── harness_boot.py
    ├── harness_heartbeat.py
    ├── harness_service.py
    ├── harness_eval.py
    ├── harness_orchestrator.py
    ├── harness_cleanup.py
    └── harness_setup_cron.py

---

📦 Installation

Prerequisites

• OpenHarness core harness installed in ~/.openclaw/workspace/harness/
• Codex CLI installed and available as codex in your $PATH
• Python 3.9+

Setup

Clone this repository into the same workspace directory, alongside the main harness:

cd ~/.openclaw/workspace/harness/
git clone https://github.com/thu-nmrc/OpenHarness-For-Codex.git openharness-for-codex

Verify Codex CLI is available:

which codex
codex --version

---

🚀 Quick Start

Step 1: Initialize a project workspace

python3 ~/.openclaw/workspace/harness/openharness-for-codex/scripts/harness_boot.py ~/my-project --init

Step 2: Fill in your requirements

Open ~/my-project/mission.md and describe what you want to build. For example:

Develop a full-stack web app "AI Resource Pack Generator".
Frontend: React + Tailwind. Backend: FastAPI.
Feature: user inputs a topic, backend calls OpenAI API to generate a resource pack, 
packages it as a ZIP for download.
Target: 3 iteration rounds.

Step 3: Trigger the Agent with one sentence

In your Agent (e.g., OpenClaw), simply say:

Read the SKILL.md in openharness-for-codex, then execute the development task in ~/my-project.
Workspace path: ~/my-project

The Agent will automatically:

1. Run harness_boot.py to check state and resume from breakpoint if needed
2. Read mission.md, design the architecture, write tech_spec.md
3. Construct a Codex Prompt and call Codex CLI to generate code
4. Run harness_service.py to install dependencies and start the service
5. Run harness_eval.py for external validation (HTTP probe + log analysis)
6. Write an iteration report, construct a fix Prompt, and loop again
7. Repeat until validation passes for the target number of rounds, then package and deliver

---

🔧 Script Reference

Script	Called By	Function
harness_boot.py	Agent	Initialize workspace / check state, output Agent-friendly action instructions
harness_heartbeat.py	Agent	State machine: start / done / fail / next_iteration / blocked / mission_complete
harness_service.py	Agent	Auto-detect project type, install deps, start/stop service, HTTP health check
harness_eval.py	Agent	External validation: code integrity + HTTP probe + log analysis → eval_report.json
harness_orchestrator.py	Agent / CLI	Core orchestrator: drives the full multi-round development loop autonomously
harness_cleanup.py	Agent	Entropy control: compress old logs, prevent context window bloat
harness_setup_cron.py	Agent	Read cron_config.md, output parameters for the schedule tool

---

🛠️ Troubleshooting

Task is blocked

1. Check the last 50 lines of logs/service.log for the root cause.
2. Manually fix the critical issue in project_src/ (e.g., dependency version conflict).
3. Reset heartbeat.md: set Current Status to idle and Consecutive Failures to 0.
4. Re-trigger the Agent.

Codex is not generating files

Verify Codex CLI is in your PATH: which codex. If using a different Agent CLI (e.g., aider), modify the run_codex() function in harness_orchestrator.py.

Service starts but eval still fails

Run python3 scripts/harness_service.py ~/my-project status to check service state, then inspect logs/service.log for detailed errors.

---

📄 License

Source-available under Business Source License 1.1.

Free for academic, research, and non-commercial use. Commercial use requires a separate license — contact syycy2021@gmail.com.