bahayonghang/codex-companion
content/skills/developer-tools-integrations/codex-companion/SKILL.md
Manage Codex background tasks, persistent job threads, adversarial code reviews, and job lifecycle (status, result, cancel) from inside any AI coding session. Use this skill proactively whenever the user wants to delegate work to Codex and check back later, run a security-focused or attack-minded code review, resume a previous Codex task, check on running Codex jobs. Also use when the user mentions "background task", "Codex job", "adversarial review", "diff review", or wants Codex to keep working while they do something else.
$ install --global
skillsauthnpx skillsauth add bahayonghang/my-claude-code-settings codex-companionInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 21, 2026, 3:10 AM186.0s30 files scanned
SKILL.md
- name:
- codex-companion
- description:
- >-
- version:
- 1.1.0
- category:
- developer-tools-integrations
- argument-hint:
- [task-description | review | adversarial-review | status | result | cancel]
Run the Codex companion runtime for $ARGUMENTS.
Script path:
$SKILL_DIR/scripts/codex-companion.mjs
Quick Start
node "$SKILL_DIR/scripts/codex-companion.mjs" review --base main # 1. Review changes
node "$SKILL_DIR/scripts/codex-companion.mjs" task "fix the bug" # 2. Delegate work
node "$SKILL_DIR/scripts/codex-companion.mjs" status # 3. Check progress
node "$SKILL_DIR/scripts/codex-companion.mjs" result <job-id> # 4. Get output
When to Use This vs the codex Skill
| Scenario | Use |
|----------|-----|
| One-off codex review or codex exec you drive manually | codex skill |
| Background jobs you check on later | codex-companion |
| Resumable multi-turn task threads | codex-companion |
| Structured adversarial review with JSON findings | codex-companion |
| Job lifecycle: status, result, cancel | codex-companion |
Prerequisites
- Verify Codex CLI is installed.
- Bash / zsh:
command -v codex - PowerShell:
Get-Command codex - If missing, tell the user to install it:
npm install -g @openai/codex
- Bash / zsh:
- If Codex is installed but not authenticated, run
codex login.- If browser login is blocked, retry with
codex login --device-authorcodex login --with-api-key
- If browser login is blocked, retry with
Mode Router
Choose one primary subcommand:
| Subcommand | Purpose | Read-only? |
|------------|---------|------------|
| review | Built-in diff-aware review of the current repo or a base branch | Yes |
| adversarial-review | Structured attack-minded review with findings first | Yes |
| task | Delegate diagnosis, research, or implementation to a persistent Codex thread | Configurable |
| status | Inspect running or recent jobs | Yes |
| result | Fetch the stored output for a finished job | Yes |
| cancel | Stop an active job | N/A |
If the user asks to "continue", "resume", "keep going", or "follow up" on prior Codex work, prefer task --resume-last.
Default Command Forms
Set a helper variable first when the session is command-heavy.
Bash / zsh
COMPANION="$SKILL_DIR/scripts/codex-companion.mjs"
PowerShell
$COMPANION = "$SKILL_DIR/scripts/codex-companion.mjs"
Then use:
node "$COMPANION" review --base main
node "$COMPANION" adversarial-review --base main
node "$COMPANION" task "investigate why the flaky test started failing"
node "$COMPANION" task --write "apply the smallest safe fix for the failing test"
node "$COMPANION" task --background --write "implement the approved refactor"
node "$COMPANION" task --resume-last "continue from the latest task and finish the next highest-value step"
node "$COMPANION" status
node "$COMPANION" result <job-id>
node "$COMPANION" cancel <job-id>
Execution Rules
- Prefer
revieworadversarial-reviewbeforetask --writewhen the user wants validation first. - Keep
reviewandadversarial-reviewread-only. Do not turn findings into fixes unless the user separately asks for a write-capabletask. - Use
task --writeonly when the user explicitly wants Codex to modify files. - Use
task --backgroundfor long-running or open-ended work. - When the user did not explicitly ask for backgrounding, keep clearly bounded work in the foreground.
- If
resultshows touched files, inspect the diff or run follow-up verification before claiming the work is complete.
Structured Output
All commands support --json for machine-readable output. The adversarial review returns findings matching the schema in $SKILL_DIR/schemas/review-output.schema.json:
- verdict:
approveorneeds-attention - findings[]: each with
severity,title,body,file,line_start,line_end,confidence,recommendation - summary: terse ship/no-ship assessment
- next_steps: suggested follow-up actions
Prompting
For delegated task runs, prefer compact, block-structured prompts. Read:
$SKILL_DIR/references/COMMANDS.mdfor the full command surface and exit codes$SKILL_DIR/references/PROMPTING.mdfor prompt contracts and XML block patterns
Error Recovery
| Problem | Solution |
|---------|----------|
| Codex is not installed | Run npm install -g @openai/codex |
| Codex is not authenticated | Run codex login (or codex login --device-auth if browser is blocked) |
| Task fails mid-execution | Check status <job-id> for error details; use task --resume-last to retry from the last thread |
| state.json corrupt or missing | The runtime auto-recovers from individual job files; if all state is lost, start fresh with a new task |
| Broker process not responding | Kill stale processes (ps aux | grep codex-companion) and retry; the broker restarts automatically |
Notes
- The companion runtime stores per-workspace job state under the OS temp directory by default (
$TMPDIR/codex-companion/). status,result, andcanceloperate on those persisted job records.- The companion skill deliberately does not implement Claude-only hooks or stop-time review gates.
- Maximum 50 jobs retained per workspace; older jobs are pruned automatically.
Related Skills
bahayonghang/goal-meta-skill
development
VerifiedTrustedCommunity
Turn vague or complex Codex tasks into strong `/goal` commands with outcome, verification, constraints, boundaries, iteration policy, completion evidence, and pause/block conditions. Use when the user asks for Codex goal instructions, Goal 指令, 目标指令, `/goal` prompts, 中文 Goal 模板, plan-to-goal interviews, success criteria, verification commands, or bounded agent work definitions.
15SKILL.mdUpdated Jun 13, 2026
bahayonghang/ast-grep
tools
VerifiedTrustedCommunity
Write, debug, and validate ast-grep structural code search rules. Use this skill when the user needs syntax-aware code search, AST pattern matching, structural refactor discovery, language-construct queries, or searches that plain text tools like rg can miss, such as finding functions with particular descendants, calls inside specific contexts, missing error handling, React hook shapes, decorators, or other Tree-sitter-backed code structures.
15SKILL.mdUpdated Jun 9, 2026
bahayonghang/goudi
development
VerifiedTrustedCommunity
Use when the user asks to ground an ambitious proposal, avoid over-grand designs, make a bold direction executable, pressure-test feasibility, prevent "too much vision and too little landing", or turn a strategy/refactor/product idea into the smallest verifiable first move with stop rules. Trigger for requests such as 落地, 先落地, 别太飘, 收一收, 可执行, 可验证, 止损, and for follow-ups after geju-style big-picture thinking. Do not trigger for ordinary code review or implementation unless the user explicitly asks to ground or shrink the plan first.
15SKILL.mdUpdated Jun 7, 2026
bahayonghang/geju
development
VerifiedTrustedCommunity
Use when the user explicitly asks to think bigger, open up the design space, challenge conservative design, avoid over-indexing on backward compatibility, escape local-detail fixation, or make a bold high-level product or architecture direction call. Use for strategic reframing, not for ordinary code review, PRD writing, implementation planning, or adversarial risk review.
15SKILL.mdUpdated Jun 7, 2026