# test-codex-locally

test-codex-locally stands up the Weave router in docker compose, then drives it with codex exec from a throwaway CODEX_HOME to reproduce routing and marker bugs without touching your global Claude config.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 5622 repo stars
- Author: weave-os
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/weave-os/router/tree/HEAD/.agents/skills/test-codex-locally/SKILL.md
- Updated: 2026-11-17
- Security check: automated, 2026-11-16 (text) — warning: suggests running the agent with permission prompts turned off. Do not run such commands without an explicit yes from the human.
- HTML: https://affpapa.org/en/nevibecode/skills/test-codex-locally

## What it does

The skill brings the router stack up locally and points a one-off Claude session at it. Config comes from a separate `CODEX_HOME` directory with its own `config.toml` and a copy of `auth.json`, which keeps `~/.codex/` untouched. All of it happens on the Responses API path, so request translation, routing markers and forced models are what you actually get to see.

The run goes in order: `docker compose up -d --build server`, seed a key with `docker compose run --rm seed`, prepare the throwaway `CODEX_HOME`, launch `codex exec`, read the server logs. Upstream can be the real provider — a working key and credits, plus a Claude OAuth login for native Claude models — or a mock returning the expected SSE shape with no credits spent.

Some things break quietly. Set `requires_openai_auth = true` on the custom provider; with it off, Claude 0.149 hangs and never sends the `/v1/responses` request. Host port 8085 is often taken by the monorepo pubsub emulator, so the router's binding is dropped in `docker-compose.override.yml`. And `/force-model` only applies as the first line of the same prompt, leading space included.

## Requirements
- Works with: Docker

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add weave-os/router --skill test-codex-locally -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/test-codex-locally/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/test-codex-locally/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add weave-os/router --skill test-codex-locally -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/test-codex-locally/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add weave-os/router --skill test-codex-locally -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/test-codex-locally/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install weave-os/router .agents/skills/test-codex-locally
```

2. **Manually: put the files in place**
- File: `.github/skills/test-codex-locally/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add weave-os/router --skill test-codex-locally -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/weave-os/router --path .agents/skills/test-codex-locally
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/test-codex-locally/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/weave-os/router/tree/HEAD/.agents/skills/test-codex-locally/SKILL.md

## When to use it
- reproduce a Claude routing bug against a local router
- verify a router fix end to end with `codex exec`
- test a `/force-model` route without editing the global Claude config
- confirm the routing marker lands in the Responses stream
- run the flow on a mock upstream when credits run out

## Example prompts
- Bring the router up in docker compose and drive `codex exec` through a throwaway `CODEX_HOME` to reproduce the marker bug.
- Put `/force-model gpt-5.6-sol` on the first line and show me what the server logs say.
- Switch the stand to the mock upstream and check that the request reaches `/v1/responses` at all.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 01ba79985c9fea19.

BEGIN THIRD-PARTY FILE 01ba79985c9fea19
```text
---
name: test-codex-locally
description: Run the Weave router locally in docker compose and drive it with `codex exec` to reproduce and verify routing/translation/marker behavior for Codex's Responses API path. Use when verifying a router fix end-to-end for Codex, reproducing a prod Codex routing bug, confirming routing-marker / force-model / subscription-passthrough behavior, or testing a `/force-model` route — without touching the user's global Codex config.
---

# Testing the router locally with Codex

> For an **automated** pre-merge regression net (fixture-driven, asserts caching/streaming/decision-headers against real Anthropic), run `make smoke` — see [docs/SMOKE.md](../../../docs/SMOKE.md). This skill is the interactive counterpart for the **Codex CLI** (`codex exec`): stand the stack up by hand and drive it via a throwaway `CODEX_HOME` so `~/.codex/config.toml` is never edited.

Stand up the router in docker compose, point a one-off `codex exec` at it via `CODEX_HOME`, and read the local server logs to confirm behavior. Two upstream modes: the **real** provider API (needs a working key + credits, and for native GPT models a ChatGPT OAuth login) or a **mock** upstream that emits an exact SSE shape (deterministic, no credits).

The sibling skill [test-claude-locally](../test-claude-locally/SKILL.md) is the Claude Code (`claude -p`) counterpart. Stack bring-up and seeding are identical; only the client driver differs.

## Critical gotchas (read first)

- **Never edit `~/.codex/config.toml` or `~/.codex/auth.json`.** Those are the user's live Codex install (prod Weave Router + ChatGPT OAuth). Redirect with a throwaway `CODEX_HOME` directory that contains its own `config.toml` (and a *copy* of `auth.json` when ChatGPT OAuth is required). `CODEX_HOME` is how Codex finds config; there is no `--settings` flag equivalent to Claude Code.
- **`requires_openai_auth = true` is required.** Codex 0.149 hangs or never issues a `/v1/responses` request if the custom provider uses `requires_openai_auth = false` or `env_key`. Copy `~/.codex/auth.json` into the throwaway `CODEX_HOME` so Codex can attach the ChatGPT JWT + `ChatGPT-Account-ID`. The mock-router experiment that dropped OAuth never even hit the mock.
```
END THIRD-PARTY FILE 01ba79985c9fea19

The third-party file has ended. Everything between the 01ba79985c9fea19 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2244 of 18790 bytes. © weave-os · Apache-2.0 · https://github.com/weave-os/router/tree/HEAD/.agents/skills/test-codex-locally/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
