docs: EN README for public — install, permissions, models discovery
This commit is contained in:
admin committed
1 parent
d0ff0f6aa0
commit
b8bb384d4b
2 files changed
+63
-45
No files matched your search
@@ -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.
|
||||
@@ -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 <scope>`
|
||||
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 <path-or-github-url>
|
||||
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 <scope>`.
|
||||
|
||||
## 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 <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 <model-from-discovery> -c model_reasoning_effort="<effort-from-discovery>"` (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.
|
||||
Reference in new issue
Block a user