boar_codex

Files (7)

• SKILL.md
• plan-read.md · briefs/
• research.md · briefs/
• codex · fixtures/bin/
• gh · fixtures/bin/
• run.mjs
• run.test.mjs

SKILL.md (first lines)

# Codex readings

Codex (the `codex` CLI, signed in with a ChatGPT plan) is a second model that reads: it researches what Claude would otherwise read itself, and it reads what Claude wrote. It never writes to the repository; every run is read-only. Claude writes the brief, starts the run, waits and reads the summary itself, with no sub-agent in between.

## The two kinds

- **research**: one precise question about public sources (start it with `--search`) or about the repository, with a criterion of done. `mpc_grilling`'s research step and `mpc_research` send their legwork here.
- **plan-read**: a second reading of something before it is relied on: a spec draft before `mpc_to-spec` publishes it, a research file Claude wrote, a decision the user handed to Claude. Nobody checks their own research: Codex reads what Claude found, and Claude checks the evidence of what Codex found.

## Steps

1. **Brief.** Copy the kind's template from `${CLAUDE_PLUGIN_ROOT}/skills/boar_codex/briefs/` (`research.md`, `plan-read.md`) to `tmp/boarlabs/codex-briefs/<run>.md` at the repository root and fill every `<…>`. Point at documents by path, issue number or link; never paste them. Done when no `<…>` is left and the brief names its criterion of done and the shape of the report.
2. **Start** the run as a background task (Bash with `run_in_background: true` and `timeout: 7200000`), so it wakes you when it ends:

   ```bash
   root="$(git rev-parse --show-toplevel)"
   node "${CLAUDE_PLUGIN_ROOT}/skills/boar_codex/run.mjs" start --kind <research|plan-read> \
     --name <run> --brief "$root/tmp/boarlabs/codex-briefs/<run>.md" [--search] [--issue <n>]...
   ```

   - `--name`: short and new, as `spec-read` or `research-pricing`; the run's folder is `tmp/boarlabs/codex/<run>/`.
   - `--issue`: every issue the brief names, once each. The run has no network unless `--search` is given, so the command saves each issue with its comments into the run folder and adds their paths to the brief.
   - `--search`: only when the work needs the web.
   - Exit code 2 means the command refused to start; its message says why.
3. **Tell the user** the log's path: the first line of the task's output, `log: …`.
4. **Wait** for the task's notification. Runs started together are waited for together.
5. **Read the summary** at the end of the task's output: `status`, `reason`, `agent`, `weekly limit` (percent used and reset, or `unknown`; past 90% it warns and still starts), `attempt`, `exit code`, `session id`, `log`, and the final message.
   - `done`: the final message is the report. Weigh every finding, sorting each as valid, invalid or needs checking, and tell the user which you took and why. A finding is evidence to check, never an order.
   - `failed`, `stalled` (its log did not grow for 12 minutes) or `timed-out` (it lasted 115 minutes): the reason and the log's tail say what went wrong. Resume it once (below).
   - `unavailable`: Codex cannot work (signed out, or out of its usage). Do the reading yourself and tell the user you did.
6. **Resume once** after a result other than `done` or `unavailable`, with a note of what went wrong, as the same kind of background task:

   ```bash
   node "${CLAUDE_PLUGIN_ROOT}/skills/boar_codex/run.mjs" resume --name <run> --note '<what went wrong>'
   ```

   It continues the recorded Codex session in the same read-only sandbox. After a second failure, do the reading yourself and tell the user, naming both logs.

## The run folder

`tmp/boarlabs/codex/<run>/` keeps `brief.md` (the saved brief with the command's own `## This run` section), `issues/<n>.md`, `run.log` (both output streams), `final.md` (the report) and `run.json` (status, attempt count, exit code, the Codex session id). Attempt two keeps its own `resume.md`, `run-2.log` and `final-2.md`. `tmp/` is gitignored by `boar_setup`; nothing here is committed.

From boarlabsxyz/skills, MIT.

More from boarlabsxyz/skills