bahayonghang/codex-companion
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/literature-mentor
tools
VerifiedTrustedCommunity
文献深度解读助手，像研究生导师一样交互式解读 Zotero 库中的学术论文，面向计算机科学、深度学习、自动化等方向（个人向）。当用户提供文献题目、DOI、PDF 或要求解读某篇论文时触发，通过 Zotero MCP 优先获取全文，并根据用户意图自动选择快速筛选、导师深读或研究复盘模式。完整深读时先完成叙事类型判断、阅读前预检、novelty 校准和作者思考路径重建，再整体概览，并基于图例、正文和表格逐图详细解读（Zotero MCP 无法提取 PDF 图片，解读基于文字信息，必要时提醒上传图片）。适用于：(1)快速判断文献是否值得深读 (2)深入理解某篇论文 (3)学习文章中的方法和技术 (4)批判性分析研究设计 (5)寻找研究灵感。需要多篇论文综合、对比或找研究空白，或 arXiv/DOI 批量规范化时，改用 paper-workbench。
16SKILL.mdUpdated Jun 21, 2026
bahayonghang/agent-skill-review
development
VerifiedTrustedCommunity
Review Codex, Claude, OpenAI, or other agent skill directories as reusable capability packages. Use when asked to audit, review, improve, score, rewrite, debrand, package, or document a SKILL.md, skill package, marketplace skill, or agent skill directory, especially when the user wants a comprehensive findings-first report with concrete patch recommendations and validation steps.
16SKILL.mdUpdated Jun 15, 2026
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.
16SKILL.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.
16SKILL.mdUpdated Jun 9, 2026