From b8bb384d4b1e546138bc6731277d937ce69c90b0 Mon Sep 17 00:00:00 2001 From: Evgeny Gamov Date: Tue, 1 Sep 2026 00:26:52 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20EN=20README=20for=20public=20=E2=80=94?= =?UTF-8?q?=20install,=20permissions,=20models=20discovery?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 10 +++++ README.md | 98 ++++++++++++++++++++++++++----------------------- 2 files changed, 63 insertions(+), 45 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fe56a04 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,10 @@ +# Contributing + +Keep PRs small and focused. Use English only. + +1. Fork, branch from `main`, make minimal changes. +2. Run relevant tests (`tests/test-run.sh` if touching `scripts/`). +3. Bump `version` in `.claude-plugin/plugin.json` if publishing. +4. Ensure `codex CLI >=0.151` and `jq` requirements are respected. +5. Open PR with clear description and verification steps. +6. Be respectful and constructive in review. diff --git a/README.md b/README.md index a9e83fb..19124b8 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,66 @@ # codex-crew -Codex CLI as a first-class Claude Code subagent: task delegation, code -review, second opinion. Inherits the user's `~/.codex/config.toml` (no -sandboxes, no restrictions), sessions are resumable, hangs are detected by a -deterministic watchdog. - -## Contents - -- `agents/codex.md` — transport subagent (sonnet). Holds the codex session: - follow-ups via SendMessage continue the same dialogue. The task must - include `cwd:`; optional `codex options:` (model/sandbox/effort) and - `review scope:`. -- `skills/codex-agent` — delegate execution. -- `skills/codex-review` — review a branch/commit/uncommitted/files. -- `skills/codex-consult` — second opinion on a spec/plan, iterate to - consensus. -- `scripts/codex-run.sh` — wrapper around `codex exec --json` with a - watchdog (`CODEX_STALL_TIMEOUT`, default 600s of output stagnation → kill; - the session continues via resume). Tests: `tests/test-run.sh`. - -## How it works - -The orchestrator spawns the `codex` subagent with a task. The subagent -writes a prompt file (transport preamble + task), launches `codex-run.sh` -in the background, and polls the status file. - -Review mode: the codex CLI can't combine a scope flag -(`--base`/`--commit`/`--uncommitted`) with a custom prompt, so with a -non-empty prompt file the script translates the scope into prompt text -automatically; with no prompt file the native `codex exec review ` -path is used. - -Prompt convention: wrapper instructions outside, the codex task between -`=== TASK FOR CODEX ===` / `=== END TASK ===` markers — the wrapper forwards -only the marked block, so it never mistakes the task for its own job, and -wrapper instructions never leak into the codex prompt. +Codex CLI as a first-class Claude Code subagent: delegate, review, consult. Respects your `~/.codex/config.toml`, sessions resumable, stall watchdog. ## Install ``` -claude plugin marketplace add -claude plugin install codex-crew@codex-crew +/plugin marketplace add smartass/codex-crew +/plugin install codex-crew@codex-crew ``` -Requires codex CLI ≥0.142. +Requires `codex CLI >=0.151` and `jq`. -Update after push (Claude Code doesn't re-fetch the cache; `plugin update` -compares the version from plugin.json — no version bump, no content update): +## How it works + +Orchestrator → `codex` subagent (`agents/codex.md`) → `scripts/codex-run.sh` → `codex exec --json` (`--skip-git-repo-check -o last.md`). Non-empty `prompt.md` is fed via stdin `-` so flags and prompt combine. Stall watchdog (`CODEX_STALL_TIMEOUT`, default 600s of event silence → kill; resume via `thread_id`). `cwd:` in task is mandatory; `codex options:` forwarded verbatim. Review scope (`--base`/`--commit`/`--uncommitted`) is translated to prompt text when a custom prompt is present (CLI forbids scope + prompt together), otherwise native `codex exec review `. + +## Skills + +| Skill | Trigger | +|---|---| +| `codex-agent` | `delegate to codex`, `have codex do` — execution, bugfix, research | +| `codex-review` | `codex review` — branch (`--base`), commit, uncommitted, or files | +| `codex-consult` | `second opinion`, `have codex review the spec/plan` — iterate to consensus (max 5 rounds) | + +Details: `skills/references/common.md`. + +## Permissions & Sandbox + +Default inherits `~/.codex/config.toml` (no flags injected). Override per-task via `codex options:`: + +- `-s read-only | workspace-write | danger-full-access` +- `--add-dir ` — extra writable directory +- `--dangerously-bypass-approvals-and-sandbox` — dangerous, only in an externally sandboxed environment + +Example: `codex options: -s workspace-write --add-dir /tmp` + +Flags are saved per-job and re-applied on `resume`. + +## Models & Reasoning + +Default from `~/.codex/config.toml` (`model`, `model_reasoning_effort`). Discovery: ``` -# 1. bump version in .claude-plugin/plugin.json, commit, push -claude plugin marketplace update codex-crew -claude plugin update codex-crew@codex-crew +./scripts/codex-models.sh +# or +codex debug models | jq '[.models[] | select(.visibility=="list") | {slug, levels: [.supported_reasoning_levels[].effort]}]' ``` -then `/reload-plugins` or restart the session (agent/skill definitions are -snapshotted on reload; hot-patching the cache doesn't work). +Pass via `codex options: -m -c model_reasoning_effort=""` (values from `scripts/codex-models.sh` output). + +## Updating + +Bump `version` in `.claude-plugin/plugin.json`, commit, push, then: + +``` +/plugin marketplace update codex-crew +/plugin update codex-crew@codex-crew +/reload-plugins +``` + +No version bump → no update (Claude Code caches by version). + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome — keep changes minimal and EN-only.