$ show leo-lilinxiao/codex-autoresearch
Codex Autoresearch is an autonomous, goal-driven experimentation CLI tool for Codex. It allows users to define a numeric target (e.g., reduce error count to zero) and then repeatedly runs a loop: the Codex model inspects the repo, makes one focused code change, the control script commits it, runs a verification command to measure the metric, keeps improvements or reverts failures, and appends audit events. The system supports both foreground (Codex Goal-driven) and background (detached controller with `codex exec` workers) modes, with strict state validation, atomic file operations, and Git-based rollback. Architecture: The codebase is split into three Python modules under `scripts/`—`autoresearch.py` (CLI and lifecycle orchestration), `autoresearch_core.py` (primitives for Git, command execution, event validation, and process management), and `autoresearch_report.py` (read-only rendering of history as terminal tables, TSV, or self-contained HTML). State is stored in `autoresearch-results/` as immutable `run.json` and append-only `events.jsonl`. The skill entrypoint is `SKILL.md`, which references three documentation files. The design emphasizes contract enforcement over silent recovery: malformed input, unexpected Git drift, or failed commands halt with precise diagnostics. The repository demonstrates high craftsmanship in defensive programming, strict JSON schema validation, atomic file writes, process tree management, and comprehensive unit/integration tests (including race condition testing for background controllers). It is a practical and well-documented example of building a reliable autonomous agent harness for codebases.
The LLM identified 2 files worth highlighting for reuse:
The core module provides a set of independent, strictly validated primitives for Git operations, atomic file I/O, JSON schema validation, command execution with timeout and process tree termination, and append-only event logging. Functions like `write_json_atomic`, `require_clean_repo`, `commit_trial`, `revert_trial`, `run_command`, `parse_json`, `validate_event`, and `terminate_process_tree` are self-contained and can be extracted into a reusable library for any project that needs robust, auditable automation with Git and shell commands. Error messages consistently include context (file paths, log locations) enabling debugging without code changes.
A read-only renderer that generates terminal tables, tab-separated values (TSV), and a fully self-contained static HTML report from a validated event log. The HTML report includes an inline SVG metric trajectory chart, scrollable experiment history table, run summary cards, and configuration details—all without any external dependencies (no JavaScript, no external images). The report respects Content Security Policy and escapes HTML entities. The core logic (`history_rows`, `render_history_table`, `render_html_report`) is cleanly separated and could be reused as a library for generating reproducible audit views from any structured event stream.