# Codex Collab

> Use when the user asks to invoke, delegate to, or collaborate with Codex on any task. Also use PROACTIVELY when an independent, non-Claude perspective from Codex would add value — second opinions on code, plans, architecture, or design decisions.

- **Type:** Skill
- **Install:** `agentstack add skill-kevin7qi-codex-collab-codex-collab`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Kevin7Qi](https://agentstack.voostack.com/s/kevin7qi)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Kevin7Qi](https://github.com/Kevin7Qi)
- **Source:** https://github.com/Kevin7Qi/codex-collab

## Install

```sh
agentstack add skill-kevin7qi-codex-collab-codex-collab
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# codex-collab

codex-collab is a bridge between Claude and Codex. It communicates with Codex via the `codex app-server` JSON-RPC protocol, giving you structured, event-driven access to Codex's capabilities — prompting, code review, tool use, and file editing.

## Collaboration Modes

- **Run** — Single-command `run` for any prompted task (research, analysis, implementation). Starts a thread, sends prompt, waits for completion, returns output.
- **Code review** — Single-command `review` for PR-style, uncommitted, or commit-level review.
- **Parallel work** — You and Codex work on different parts simultaneously. Start multiple threads.
- **Research** — Spin up a read-only Codex session to investigate something while you continue other work.

## Run Command (Recommended for Prompted Tasks)

The `run` command handles prompted tasks in one call: starts a thread, sends the prompt, waits for the turn to complete, and prints output.

```bash
# Research task
codex-collab run "what does this project do?" -s read-only --content-only

# Implementation task
codex-collab run "add input validation to the login form" --content-only

# Resume an existing thread (preserves conversation context)
codex-collab run --resume  "now check the error handling" --content-only

# Specify working directory (omit -d if already in the project dir)
codex-collab run "investigate the auth module" -d /path/to/project --content-only
```

**IMPORTANT — Execution rules for ALL `codex-collab` Bash commands:**
- Always use `dangerouslyDisableSandbox=true` — the tool writes to `~/.codex-collab/` which is outside the sandbox allowlist.
- For `run` and `review`: also use `run_in_background=true` — these take minutes. After launching, tell the user it's running and end your turn. **While running**: do NOT poll, block, wait, or spawn an agent to monitor — you will be notified automatically when the task finishes. If other tasks complete while Codex is running, handle them normally without checking on Codex. **When notified**: read the completed task's output (the notification includes it or use `Read` on the output file), then present the results to the user.
- For all other commands (`kill`, `threads`, `progress`, `output`, `approve`, `decline`, `clean`, `delete`, `models`, `health`): run in the **foreground** — they complete in seconds.

If the user asks about progress mid-task, use `TaskOutput(block=false)` to read the background output stream, or:

```bash
codex-collab progress 
```

## Code Review

**For a standard PR review, call `review` with NO prompt string.** The default `pr` mode runs the built-in structured diff workflow against the default branch:

```bash
# PR-style review against default branch (default — NO prompt)
codex-collab review -d /path/to/project --content-only

# Review uncommitted changes
codex-collab review --mode uncommitted -d /path/to/project --content-only

# Review a specific commit
codex-collab review --mode commit --ref abc1234 -d /path/to/project --content-only
```

**Passing a prompt string flips to `custom` mode** — it sends your text as free-form instructions and bypasses the built-in diff workflow. Use this when a focused or targeted review fits better than the default diff workflow (e.g., "review this for security issues", "check the error handling only"). Default to `pr` mode for general PR reviews:

```bash
codex-collab review "Focus on security issues in auth" -d /path/to/project --content-only
```

**Reviews are one-shot.** Each `review` call runs a single review inside a transient review sub-thread and exits — you cannot continue the review itself or ask the reviewer follow-up questions. For follow-ups on findings, use `run --resume ` with the relevant review output in the prompt.

`review --resume ` is useful for running a review with context from a task thread Codex has already been working in. It forks that context into an ephemeral read-only review thread, so the original task thread is not reconfigured or mutated. `review` with no `--resume` creates an ephemeral thread that disappears after the review — use this for standalone reviews with no prior context.

Review modes: `pr` (default), `uncommitted`, `commit`, `custom`

## Context Efficiency

- **Use `--content-only`** when reading output — prints only the result text, suppressing progress lines.
- **`run` and `review` print results on completion** — no separate `output` call needed.
- **Use `output `** only to re-read the full log for a previously completed thread.

## Resuming Threads

When consecutive tasks relate to the same project, resume the existing thread. Codex retains the conversation history, so follow-ups like "now fix what you found" or "check the tests too" work better when Codex already has context from the previous exchange. Start a fresh thread when the task is unrelated or targets a different project.

**If the user asks to continue or follow up on a prior task but you don't have the thread ID in context**, follow this discovery flow:

1. `codex-collab threads --discover` — see top 5 recent threads (server + local).
2. If unsure which thread is right, `codex-collab peek ` to see the last exchange of a candidate.
3. For very long threads where peek alone isn't enough, spawn a subagent with `codex-collab peek  --limit 100 --full` and ask it to summarize. This keeps the firehose out of your own context.
4. `codex-collab run --resume  "..."` to continue.

Only run `--discover` when a resume is actually wanted — it's a lookup performed on demand.

The `--resume` flag accepts both ID formats:
- `--resume ` — 8-char hex short ID (supports prefix matching, e.g., `a1b2`)
- `--resume ` — Full Codex thread ID (UUID, e.g., `019d680c-7b23-7f22-ab99-6584214a2bed`)

| Situation | Action |
|-----------|--------|
| Same project, new prompt | `codex-collab run --resume  "prompt"` |
| Same project, want review | `codex-collab review --resume ` |
| Different project | Start new thread |
| Thread stuck / errored | `codex-collab kill ` then start new |

If you've lost track of the thread ID, use `codex-collab threads` to find active threads.

## Checking Progress

If the user asks about a running task, use `TaskOutput(block=false)` (with the background task ID returned when launching the command) to read the output stream. The codex-collab thread short ID appears in the first progress line (e.g., `[codex] Thread a1b2c3d4 started`) — handy when you need it but don't have it. If you need just the tail of the log without the full stream:

```bash
codex-collab progress 
```

Note: `` is the codex-collab thread short ID (8-char hex from the output), not the Claude Code background task ID. If you don't have it, run `codex-collab threads`.

Progress lines stream in real-time during execution:
```
[codex] Thread a1b2c3d4 started (gpt-5.4, workspace-write)
[codex] Turn started
[codex] Running: npm test
[codex] Edited: src/auth.ts (update)
[codex] Turn completed (2m 14s, 1 file changed)
```

## Approvals

By default, Codex auto-approves all actions (`--approval never`). For stricter control:

```bash
# Require approval for Codex-initiated actions
codex-collab run "refactor the auth module" --approval on-request --content-only
```

When an approval is needed, the progress output will show:
```
[codex] APPROVAL NEEDED
[codex]   Command: rm -rf node_modules
[codex]   Approve: codex-collab approve 
[codex]   Decline: codex-collab decline 
```

Respond with `approve` or `decline`:
```bash
codex-collab approve 
codex-collab decline 
```

## CLI Reference

### Run

```bash
codex-collab run "prompt" [options]               # New thread, send prompt, wait, print output
codex-collab run --resume  "prompt" [options]  # Resume existing thread
codex-collab run "prompt" -s read-only             # Read-only sandbox
```

### Review

```bash
codex-collab review [options]                      # PR-style (default)
codex-collab review --mode uncommitted [options]   # Uncommitted changes
codex-collab review --mode commit [options]        # Latest commit
codex-collab review --mode commit --ref      # Specific commit
codex-collab review "instructions" [options]       # Custom review
codex-collab review --resume  [options]        # Resume existing thread
```

### Reading Output

```bash
codex-collab output                 # Full log for thread
codex-collab progress               # Recent activity (tail of log)
```

### Thread Management

```bash
codex-collab threads                    # List threads (current session)
codex-collab threads --all              # List all threads (no display limit)
codex-collab threads --discover         # Discover threads from Codex server (top 5 by default)
codex-collab peek                   # Show last exchange (default) from server
codex-collab peek  --limit 10 --full  # Show 10 items including non-message types
codex-collab kill                   # Stop a running thread
codex-collab delete                # Archive thread, delete local files
codex-collab clean                      # Delete old logs and stale mappings
```

Note: `jobs` still works as a deprecated alias for `threads`.

### Utility

```bash
codex-collab config                     # Show persistent defaults
codex-collab config model gpt-5.3-codex # Set default model
codex-collab config model --unset       # Unset a key (return to auto)
codex-collab config --unset             # Unset all keys (return to auto)
codex-collab models                     # List available models
codex-collab approve               # Approve a pending request
codex-collab decline               # Decline a pending request
codex-collab health                     # Check prerequisites
```

### Options

| Flag | Description |
|------|-------------|
| `-m, --model ` | Model name (default: auto — latest available) |
| `-r, --reasoning ` | Reasoning effort: low, medium, high, xhigh (default: auto — highest for model) |
| `-s, --sandbox ` | Sandbox: read-only, workspace-write, danger-full-access (default: workspace-write; review always uses read-only) |
| `-d, --dir ` | Working directory (default: cwd) |
| `--resume ` | Resume existing thread (run and review) |
| `--timeout ` | Turn timeout in seconds (default: 1200). Do not lower this — Codex tasks routinely take 5-15 minutes. Increase for large reviews or complex tasks. |
| `--approval ` | Approval policy: never, on-request, on-failure, untrusted (default: never) |
| `--mode ` | Review mode: pr, uncommitted, commit, custom |
| `--ref ` | Commit ref for --mode commit |
| `--all` | List all threads with no display limit (threads command) |
| `--discover` | Query Codex server for threads not in local index (threads command) |
| `--json` | JSON output (threads, peek commands) |
| `--full` | Include all item types in peek output (default shows messages only) |
| `--template ` | Prompt template for run command (checks `~/.codex-collab/templates/` first, then built-in) |
| `--content-only` | Print only result text (no progress lines) |
| `--limit ` | Limit items shown |

## Templates

Use `--template ` with the `run` command to wrap your prompt in a structured template.

Custom templates: place `.md` files with frontmatter in `~/.codex-collab/templates/`, then re-run the installer.

## TUI Handoff

To hand off a thread to the Codex TUI, look up the full thread ID with `codex-collab threads --json` and then run `codex resume ` in the terminal.

## Tips

- **`run --resume` requires a prompt.** `review --resume` works without one (it uses the review workflow), but `run --resume ` will error if no prompt is given.
- **Omit `-d` if already in the project directory** — it defaults to cwd. Only pass `-d` when the target project differs from your current directory.
- **Multiple concurrent threads** are supported. Threads share a per-workspace broker for efficient resource usage.
- **Validate Codex's findings.** After reading Codex's review or analysis output, verify each finding against the actual source code before presenting to the user. Drop false positives, note which findings you verified.
- **Per-workspace scoping.** Threads and state are scoped per workspace (git repo root). Different repos have independent thread lists.
- **First invocation per workspace** may take slightly longer to initialize; subsequent calls in the same session reuse the connection context.

## Error Recovery

| Symptom | Fix |
|---------|-----|
| "codex CLI not found" | Install: `npm install -g @openai/codex` |
| Turn timed out | Increase `--timeout` (e.g., `--timeout 1800` for 30 min). Large reviews and complex tasks often need more than the 20-min default. |
| Thread not found | Use `codex-collab threads` to list active threads |
| Process crashed mid-task | Resume with `--resume ` — thread state is persisted |
| Approval request hanging | Run `codex-collab approve ` or `codex-collab decline ` |

## Prerequisites

Requires bun and codex CLI on PATH. Run `codex-collab health` to verify.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Kevin7Qi](https://github.com/Kevin7Qi)
- **Source:** [Kevin7Qi/codex-collab](https://github.com/Kevin7Qi/codex-collab)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kevin7qi-codex-collab-codex-collab
- Seller: https://agentstack.voostack.com/s/kevin7qi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.