Skip to content

fix: harden tool lifecycle and current-state docs #168

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
evelynadriaan wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix: harden tool lifecycle and current-state docs #168

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,3 +44,4 @@ temp/

# Jest cache
.jest/
.codex
8 changes: 5 additions & 3 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Sessions enable multi-turn conversations with Codex:
2. **Subsequent requests with same sessionId**: Uses `codex exec resume <conversation-id>` (native Codex resume)
3. **Fallback**: If no conversation ID exists, manually builds enhanced prompt from conversation history

**Important**: When resuming sessions, `sandbox`, `fullAuto`, and `workingDirectory` parameters are NOT applied (Codex CLI limitation).
**Important**: When resuming sessions, `sandbox` and `workingDirectory` are not applied. This server does forward `fullAuto` and `bypassApprovals` on resume, but those flags still depend on the installed Codex CLI supporting them.

### Streaming Progress

Expand Down Expand Up @@ -113,16 +113,18 @@ codex exec --model X --sandbox Y [-c config=value] --skip-git-repo-check "prompt

**Resume mode** (existing conversations):
```
codex exec --skip-git-repo-check -c model="X" -c model_reasoning_effort="Y" resume <conversation-id> "prompt"
codex exec --skip-git-repo-check -c model="X" -c model_reasoning_effort="Y" [--full-auto] [--dangerously-bypass-approvals-and-sandbox] resume <conversation-id> "prompt"
```

Note: Config flags (`-c`) must come BEFORE the subcommand (`exec` or `resume`).

### Environment Variables

- `CODEX_DEFAULT_MODEL`: Default model for codex/review tools (default: `gpt-5.3-codex`)
- `CODEX_DEFAULT_MODEL`: Default model for codex/review tools (default: `gpt-5.4`)
- `CODEX_MCP_CALLBACK_URI`: Static MCP callback URI passed to Codex (override via tool arg)
- `STRUCTURED_CONTENT_ENABLED`: Enable `structuredContent` in responses (default: false)
- `CODEX_MCP_DEBUG_STARTUP`: Emit startup banner for debugging (default: false)
- `CODEX_MCP_DEBUG_COMMANDS`: Emit command argv/stderr for debugging (default: false)

## TypeScript Configuration

Expand Down
10 changes: 10 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,8 @@ Use review with uncommitted true to review my local changes
```
Use codex with model "o3" and reasoningEffort "high" for complex analysis
Use codex with fullAuto true and sandbox "workspace-write" for automated tasks
Use codex with bypassApprovals true only inside an externally sandboxed environment
Use codex with timeoutMs 300000 for long-running tasks
Use codex with callbackUri "http://localhost:1234/callback" for static callbacks
Use codex to return structuredContent with threadId metadata when available
```
Expand All @@ -107,9 +109,17 @@ Use websearch with query "React Server Components" and searchDepth "full"
- **[API Reference](docs/api-reference.md)** — Full tool parameters and response formats
- **[Session Management](docs/session-management.md)** — How conversations work
- **[Codex CLI Integration](docs/codex-cli-integration.md)** — Version compatibility and CLI details
- **[Claude Code Lifecycle Investigation](docs/claude-code-lifecycle-investigation.md)** — Reproductions, fixes, and what Claude tears down itself

## Environment Variables
- `CODEX_DEFAULT_MODEL`: Override the default model for `codex` and `review` (default `gpt-5.4`)
- `CODEX_MCP_CALLBACK_URI`: Static MCP callback URI passed to Codex when set (overridden by `callbackUri` tool arg)
- `CODEX_TOOL_TIMEOUT_MS`: Timeout in milliseconds for serialized tool calls (default `120000`)
- `STRUCTURED_CONTENT_ENABLED`: Emit `structuredContent` alongside text metadata when truthy
- `CODEX_MCP_DEBUG_STARTUP`: Set to `1`, `true`, `yes`, or `on` to emit the startup banner on stderr for debugging
- `CODEX_MCP_DEBUG_COMMANDS`: Set to `1`, `true`, `yes`, or `on` to emit command argv and stderr for debugging

`timeoutMs` on the `codex` tool overrides `CODEX_TOOL_TIMEOUT_MS` for a single request.

## Development

Expand Down
8 changes: 6 additions & 2 deletions docs/TODO.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Codex MCP Server - TODO

This file is backlog-oriented. Do not treat the "Implemented" section below as
the current runtime source of truth; check `README.md`, `docs/api-reference.md`,
and the code first.

## Features from Codex CLI v0.98.0

These features were introduced/stabilized in Codex CLI v0.98.0 but are not yet implemented in this MCP server.
Expand Down Expand Up @@ -50,11 +54,11 @@ These features were introduced/stabilized in Codex CLI v0.98.0 but are not yet i

## Implemented in v1.3.4+

### ✅ GPT-5.3-Codex Model
### ✅ GPT-5.4 Default Model
- **Status**: Implemented
- **Description**: New default model
- **Changes**:
- Updated `DEFAULT_CODEX_MODEL` constant to `'gpt-5.3-codex'`
- Updated `DEFAULT_CODEX_MODEL` constant to `'gpt-5.4'`
- Updated tool definitions to reflect new default
- Single source of truth for model updates

Expand Down
Loading