bahayonghang/codex-companion
content/skills/ai-llm-skills/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: Apr 3, 2026, 7:25 PM4.7s30 files scanned
SKILL.md
- name:
- codex-companion
- description:
- >-
- version:
- 1.1.0
- category:
- development-tools
- 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/code-refactor
development
VerifiedTrustedCommunity
Implement safe, behavior-preserving code refactors after inspecting the existing project. Use when the user asks to refactor code, split large files or modules, extract functions or methods, reduce duplicated logic, rename confusing classes/functions/variables, improve code comments, remove unused or dead code, or says 重构代码, 拆分模块, 提取方法, 减少重复代码, 优化命名, 优化注释, 删除未调用代码. For broad refactor requests, plan safe slices and wait for approval; for narrow scoped requests, directly implement the smallest verifiable slice.
15SKILL.mdUpdated Jun 6, 2026
bahayonghang/codex-dynamic-workflows
development
VerifiedTrustedCommunity
Use only when the user explicitly asks for swarm, subagents, parallel agents, dynamic workflow, multi-agent orchestration, 多智能体编排, or when the task truly needs coordinated research plus implementation plus review plus verification packets. Do not use for ordinary code review, planning-only work, single-line bugfixes, routine audits, or migrations unless orchestration is requested or at least two independent workflow dimensions are present.
15SKILL.mdUpdated Jun 4, 2026
bahayonghang/code-quality-review
development
VerifiedTrustedCommunity
Run a code quality review focused on maintainability, structure, abstraction quality, file growth, branching complexity, boundary cleanliness, and refactoring opportunities. Use when the user asks for code quality review, code review, maintainability review, architecture quality review, PR code quality feedback, 代码质量审查, 代码质量 review, 可维护性审查, 架构质量审查, or review comments about code structure. Do not use for pure security review, formatting-only review, performance profiling, or implementation tasks unless the user also asks for a code quality review.
15SKILL.mdUpdated Jun 4, 2026
bahayonghang/spark
development
VerifiedTrustedCommunity
Plan-first brainstorming workflow that turns an idea into an approved Markdown implementation plan by default. Use when the user wants to brainstorm, design, scope, or plan a feature/spec before implementation. Spark explores project context, asks only blocking questions, writes the plan under the project root's .plannings/YYYY-MM-DD-feature-slug.md path, self-reviews it, and waits for user approval. Create an HTML or visual plan/spec only when the user explicitly asks for HTML, browser-viewable, or visual output; save the paired .html beside the Markdown plan.
15SKILL.mdUpdated May 29, 2026