菜单
Run Codex in a persistent tmux session with signal-based completion so long tasks survive conversation death. Use when work may take 5+ minutes, needs background execution, or must remain retrievable after the calling session ends.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Order user-facing questions by dependency. Use when two or more clarifications may depend on one another, a high-impact fork should be resolved before details, a plan needs a decision-tree interview, or a visual choice should be previewed before asking.
Critically evaluate a planned or existing feature against the project's vision and decide whether to keep, sharpen, park, or cut it — favoring depth on the core loop over breadth of surface area. Use for "is this in scope", "does this fit the vision", "prune scope", "feature creep", "scope creep", "depth not breadth", "should we remove this", "audit features against the vision", "why does this feature exist", "agents keep adding WOW features", "keep this out of scope", maintaining an OUT_OF_SCOPE.md ledger, patrolling a repo for re-added parked/cut features, or gating proposed work items (beads/plans) before they enter the backlog. Read-only by default: it recommends and records; it does not delete code without explicit approval.
Deploy, rollback, debug, and operate Docker or VPS stacks, Pages or edge frontends, packages, and app-store releases using a skillbox client overlay. Also design or migrate repo-owned local self-test and self-release paths that move avoidable build, test, and deploy work off paid GitHub Actions. Use when deploying code, reducing Actions spend, creating a self-deploy or self-test path, checking health, reviewing logs, comparing env rollout plans, validating package publishing, or working in SSH dev environments where production constraints matter.
Decompose complex work into a Beads-backed execution graph with generated `WORKGRAPH.md` views, then run an NTM-style swarm by ready frontier with no write overlap. Use before parallel execution for large-ish, UI-facing, multi-file, multi-domain, naturally parallel, naturally orchestrated, subgoal-oriented, or review-sensitive tasks.
Plan new multi-repo domain slices, assess plan quality, or orchestrate implementation from an accepted slice plan. Use for "plan the X slice", multi-repo feature planning, API contract design, "implement the X slice", or slice-quality review; not for bug fixes, small refactors, or single-repo work. When a slice premise depends on live external reality rather than internal repo evidence, run a bounded GPT-5 Pro / Deep Research gate before committing to the plan.
Three modes: audit active implementations against plan, retire completed slices into lean COMPLETED.md summaries, and retire-session consolidation of DONE session plans. Use for review/audit slice, what's left checks, retire/close out/finalize slice, or retire session plans workflows.
| name | codex-tmux |
| type | utility |
| description | Run Codex in a persistent tmux session with signal-based completion so long tasks survive conversation death. Use when work may take 5+ minutes, needs background execution, or must remain retrievable after the calling session ends. |
| license | MIT |
Run Codex non-interactively in a detached tmux session. The calling skill launches it, starts a background waiter, and continues — or dies. Either way the work completes and the result is retrievable.
This skill is a detached transport wrapper, not an NTM-style swarm orchestrator. Use it only when detached single-session survivability is the actual requirement.
Start the first progress update with the exact prefix Using codex-tmux.
Preferred format:
Using codex-tmux to run a detached Codex session. First I will launch the tmux worker and capture the result handle.
Shared cross-skill rules live in references/orchestration-contract.md. Use that file for detached review and background-result collection semantics.
| Use Claude Code subagents when | Use codex-tmux when |
|---|---|
| Task completes in < 2 minutes | Task may take 5+ minutes |
| Needs Claude Code tools (Edit, Read, Glob, Grep, Task) | Needs only filesystem + git |
| Multiple parallel fast tasks | Single slow quality gate / review |
| Context from conversation is useful | Fresh context is better (no orchestrator bias) |
| Must complete within this session | Must survive session death |
Calling skill or workflow
├── Builds prompt string
├── Calls: python3 codex-tmux/scripts/run.py launch --task "..." --cd <repo>
├── Starts background wait helper: python3 codex-tmux/scripts/run.py wait --session <name>
│ └── BLOCKS until Codex signals, then prints result.json
├── Tells user the session name only when detached survivability matters
└── Continues conversation (or session dies — both are fine)
Path A (conversation alive):
Codex finishes → signals channel → background wait helper unblocks
→ runtime task/session handle returns result.json → calling skill reports to user
Path B (conversation died):
Codex finishes → signals channel (no listener, fine)
→ macOS notification → tmux display-message
→ User checks: tmux a -t <session> OR cat <result_file>
No recursive agents. No claude --resume. The signal is a dumb tmux primitive.
gpt-5.6-sol. If SOL is unavailable and the task is planning,
architecture, synthesis, review, or final authority, use gpt-5.6-terra at
ultra. For bounded or budget-sensitive non-authority work, gpt-5.4,
gpt-5.4-mini, and codex-mini-latest are also allowed. Older
gpt-5.x-codex variants remain out of scope for this skill.medium. Use SOL max for pivotal/high-consequence planning
or when another model is demonstrably struggling. Use ultra for the Terra
planning/authority fallback, and only when SOL is unavailable.The calling skill builds the full prompt string. codex-tmux does NOT generate prompts — it's a transport layer. The calling skill also owns most user messaging. Treat codex-tmux as infrastructure unless the user explicitly needs the detached-session handle.
python3 ~/.claude/skills/codex-tmux/scripts/run.py launch \
--task "<your prompt string>" \
--cd "<repo working directory>"
Defaults are gpt-5.6-sol and medium reasoning. Use --reasoning-effort max for pivotal planning or when another model is struggling. If SOL is unavailable for a planning/authority task, pass --model gpt-5.6-terra --reasoning-effort ultra. For routine or budget-sensitive work, pass --model gpt-5.4, --model gpt-5.4-mini, or --model codex-mini-latest.
The launcher runs codex --search exec --dangerously-bypass-approvals-and-sandbox
inside the tmux wrapper so detached research and commit tasks do not hang on
browser/search or approval prompts.
The script outputs JSON to stdout:
{
"session": "codex-20260220-143022",
"signal_channel": "codex-20260220-143022-done",
"result_file": "/tmp/codex-tmux/codex-20260220-143022.json",
"wait_command": "python3 ~/.claude/skills/codex-tmux/scripts/run.py wait --session codex-20260220-143022 --result-dir /tmp/codex-tmux"
}
And a human-friendly summary to stderr:
Codex launched: codex-20260220-143022
Watch live: tmux a -t codex-20260220-143022
Result: /tmp/codex-tmux/codex-20260220-143022.json
Signal: tmux wait-for codex-20260220-143022-done
Kill: tmux kill-session -t codex-20260220-143022
Immediately after launching, start a background wait helper:
# run_in_background: true, timeout: 600000
python3 ~/.claude/skills/codex-tmux/scripts/run.py wait --session <session-name>
Only surface the session details when:
Otherwise keep the detail minimal and continue with the calling workflow.
Codex running in: codex-20260220-143022
Watch live: tmux a -t codex-20260220-143022
Status: python3 ~/.claude/skills/codex-tmux/scripts/run.py status --session codex-20260220-143022
If the conversation is still alive, prefer the background wait helper above.
Use the session status / result commands only for polling, timeout recovery, or manual inspection:
python3 ~/.claude/skills/codex-tmux/scripts/run.py result --session <session-name>
python3 scripts/run.py launch \
--task "prompt string" \
--cd ~/repos/myapp \
[--prefix codex] # session name prefix (default: codex)
[--result-dir /tmp/codex-tmux] # where to write results (default: /tmp/codex-tmux)
[--model gpt-5.6-sol] # default; Terra is the SOL-unavailable planning/authority fallback
[--reasoning-effort medium] # default; SOL escalation=max, Terra fallback=ultra
[--codex-bin codex] # path to codex binary (default: codex)
python3 scripts/run.py status --session <session-name>
Returns JSON with status (running | completed | completed_no_result), has_result, and optional tail (last 30 lines of tmux pane output if still running).
python3 scripts/run.py wait --session <session-name>
Blocks on the session completion signal, then prints the same JSON as result.
Use this for background-task handles instead of spelling raw tmux wait-for ... && cat ... in calling skills.
python3 scripts/run.py result --session <session-name>
Returns the result JSON written by the wrapper script. Shape:
{
"session": "codex-20260220-143022",
"exit_code": 0,
"commit_hash": "abc1234..." | null,
"commit_message": "feat: ...",
"completed_at": "2026-02-20T14:35:25Z"
}
The wrapper script always writes a result JSON, even on failure. It detects new commits by comparing HEAD before and after the Codex run. On error, the tmux session stays alive for tmux a -t <session> inspection.
Before reporting completion, inspect the result JSON with run.py result or
the background waiter output and verify:
pytest, has been run or
explicitly reported as unavailableIf the result file is missing, report completed_no_result as a transport
failure and inspect the live tmux tail before deciding whether to relaunch.
If tmux is unavailable, do not pretend this skill ran. Fall back to direct
Codex only when detached survivability is no longer required, and state that
the work will not survive the caller session. If the Codex binary is missing,
surface the prerequisite blocker with the exact launch command that failed.
Three channels fire on completion (any may be dead, all are best-effort):