Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
5 changes: 0 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,6 @@ Set these in `~/.opencode/openhax-codex-config.json` (applies to all models):

- `codexMode` (default `true`): enable the Codex ↔ OpenCode bridge prompt and tool remapping
- `enablePromptCaching` (default `true`): keep a stable `prompt_cache_key` so Codex can reuse cached prompts
- `enableCodexCompaction` (default `true`): allow `/codex-compact` behavior once upstream support lands
- `autoCompactTokenLimit` (optional): trigger Codex compaction after an approximate token threshold
- `autoCompactMinMessages` (default `8`): minimum conversation turns before auto-compaction is considered

Example:

Expand Down Expand Up @@ -565,8 +562,6 @@ If you want to customize settings yourself, you can configure options at provide
>
> † **Extra High reasoning**: `reasoningEffort: "xhigh"` provides maximum computational effort for complex, multi-step problems and is only available on `gpt-5.1-codex-max`.

See [Plugin-Level Settings](#plugin-level-settings) above for global toggles. Below are provider/model examples.

#### Global Configuration Example

Apply settings to all models:
Expand Down
49 changes: 28 additions & 21 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,21 +47,25 @@ Complete reference for configuring the OpenHax Codex Plugin.
Controls computational effort for reasoning.

**GPT-5 Values:**

- `minimal` - Fastest, least reasoning
- `low` - Light reasoning
- `medium` - Balanced (default)
- `high` - Deep reasoning

**GPT-5-Codex Values:**

- `low` - Fastest for code
- `medium` - Balanced (default)
- `high` - Maximum code quality

**Notes**:

- `minimal` auto-converts to `low` for gpt-5-codex (API limitation)
- `gpt-5-codex-mini*` only supports `medium` or `high`; lower settings are clamped to `medium`

**Example:**

```json
{
"options": {
Expand All @@ -75,10 +79,12 @@ Controls computational effort for reasoning.
Controls reasoning summary verbosity.

**Values:**

- `auto` - Automatically adapts (default)
- `detailed` - Verbose summaries

**Example:**

```json
{
"options": {
Expand All @@ -92,14 +98,17 @@ Controls reasoning summary verbosity.
Controls output length.

**GPT-5 Values:**

- `low` - Concise
- `medium` - Balanced (default)
- `high` - Verbose

**GPT-5-Codex:**

- `medium` only (API limitation)

**Example:**

```json
{
"options": {
Expand All @@ -117,6 +126,7 @@ Array of additional response fields to include.
**Why needed**: Enables multi-turn conversations with `store: false` (stateless mode)

**Example:**

```json
{
"options": {
Expand All @@ -132,13 +142,15 @@ Controls server-side conversation persistence.
**⚠️ Required**: `false` (for AI SDK 2.0.50+ compatibility)

**Values:**

- `false` - Stateless mode (required for Codex API)
- `true` - Server-side storage (not supported by Codex API)

**Why required:**
AI SDK 2.0.50+ automatically uses `item_reference` items when `store: true`. The Codex API requires stateless operation (`store: false`), where references cannot be resolved.

**Example:**

```json
{
"options": {
Expand Down Expand Up @@ -241,6 +253,7 @@ Different settings for different models:
- **`id` field**: DEPRECATED - not used by OpenAI provider

**Example Usage:**

```bash
# Use the config key in CLI
opencode run "task" --model=openai/my-custom-id
Expand Down Expand Up @@ -323,6 +336,7 @@ Different agents use different models:
Global config has defaults, project overrides for specific work:

**~/.config/opencode/opencode.json** (global):

```json
{
"plugin": ["@openhax/codex"],
Expand All @@ -338,6 +352,7 @@ Global config has defaults, project overrides for specific work:
```

**my-project/.opencode.json** (project):

```json
{
"provider": {
Expand All @@ -362,55 +377,39 @@ Advanced plugin settings in `~/.opencode/openhax-codex-config.json`:
```json
{
"codexMode": true,
"enableCodexCompaction": true,
"autoCompactTokenLimit": 12000,
"autoCompactMinMessages": 8
"enablePromptCaching": true
}
```

### Log file management

Control local request/rolling log growth:

- `CODEX_LOG_MAX_BYTES` (default: 5_242_880) - rotate when the rolling log exceeds this many bytes.
- `CODEX_LOG_MAX_FILES` (default: 5) - number of rotated log files to retain (plus the active log).
- `CODEX_LOG_QUEUE_MAX` (default: 1000) - maximum buffered log entries before oldest entries are dropped.

### CODEX_MODE

**What it does:**

- `true` (default): Uses Codex-OpenCode bridge prompt (Task tool & MCP aware)
- `false`: Uses legacy tool remap message
- Bridge prompt content is synced with the latest Codex CLI release (ETag-cached)

**When to disable:**

- Compatibility issues with OpenCode updates
- Testing different prompt styles
- Debugging tool call issues

**Override with environment variable:**

```bash
CODEX_MODE=0 opencode run "task" # Temporarily disable
CODEX_MODE=1 opencode run "task" # Temporarily enable
```

### enableCodexCompaction

Controls whether the plugin exposes Codex-style compaction commands.

- `true` (default): `/codex-compact` is available and auto-compaction heuristics may run if enabled.
- `false`: Compaction commands are ignored and OpenCode's own prompts pass through untouched.

Disable only if you prefer OpenCode's host-side compaction or while debugging prompt differences.

### autoCompactTokenLimit / autoCompactMinMessages

Configures the optional auto-compaction heuristic.

- `autoCompactTokenLimit`: Approximate token budget (based on character count ÷ 4). When unset, auto-compaction never triggers.
- `autoCompactMinMessages`: Minimum number of conversation turns before auto-compaction is considered (default `8`).

When the limit is reached, the plugin injects a Codex summary, stores it for future turns, and replies: “Auto compaction triggered… Review the summary then resend your last instruction.”

### Prompt caching

- When OpenCode provides a `prompt_cache_key` (its session identifier), the plugin forwards it directly to Codex.
Expand All @@ -429,12 +428,14 @@ When the limit is reached, the plugin injects a Codex summary, stores it for fut
## Configuration Files

**Provided Examples:**

- [config/full-opencode.json](../config/full-opencode.json) - Complete with 11 variants (adds Codex Mini presets)
- [config/minimal-opencode.json](../config/minimal-opencode.json) - Minimal setup

> **Why choose the full config?** OpenCode's auto-compaction and usage widgets rely on the per-model `limit` metadata present only in `full-opencode.json`. Use the minimal config only if you don't need those UI features.

**Your Configs:**

- `~/.config/opencode/opencode.json` - Global config
- `<project>/.opencode.json` - Project-specific config
- `~/.opencode/openhax-codex-config.json` - Plugin config
Expand All @@ -458,6 +459,7 @@ DEBUG_CODEX_PLUGIN=1 opencode run "test" --model=openai/your-model-name
```

Look for:

```
[openhax/codex] Model config lookup: "your-model-name" → normalized to "gpt-5-codex" for API {
hasModelSpecificConfig: true,
Expand Down Expand Up @@ -512,6 +514,7 @@ Old verbose names still work:
```

**Benefits:**

- Cleaner: `--model=openai/gpt-5-codex-low`
- Matches Codex CLI preset names
- No redundant `id` field
Expand Down Expand Up @@ -608,9 +611,11 @@ Old verbose names still work:
**Cause**: Config key doesn't match model name in command

**Fix**: Use exact config key:

```json
{ "models": { "my-model": { ... } } }
```

```bash
opencode run "test" --model=openai/my-model # Must match exactly
```
Expand All @@ -630,9 +635,11 @@ Look for `hasModelSpecificConfig: true` in debug output.
**Cause**: Model normalizes before lookup

**Example Problem:**

```json
{ "models": { "gpt-5-codex": { "options": { ... } } } }
```

```bash
--model=openai/gpt-5-codex-low # Normalizes to "gpt-5-codex" before lookup
```
Expand Down
22 changes: 6 additions & 16 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,7 @@ Add this to `~/.config/opencode/opencode.json`:
```

**What you get:**

- ✅ GPT-5 Codex (Low/Medium/High reasoning)
- ✅ GPT-5 (Minimal/Low/Medium/High reasoning)
- ✅ gpt-5-mini, gpt-5-nano (lightweight variants)
Expand Down Expand Up @@ -290,6 +291,7 @@ opencode
```

**When to update:**

- New features released
- Bug fixes available
- Security updates
Expand All @@ -313,6 +315,7 @@ For plugin development or testing unreleased changes:
**Note**: Must point to `dist/` folder (built output), not root.

**Build the plugin:**

```bash
cd codex
npm install
Expand Down Expand Up @@ -355,11 +358,13 @@ ls ~/.opencode/logs/codex-plugin/
**Prompt caching is enabled by default** to minimize your costs.

### What This Means

- Your conversation context is preserved across turns
- Token usage is significantly reduced for multi-turn conversations
- Lower overall costs compared to stateless operation

### Managing Caching

Create `~/.opencode/openhax-codex-config.json`:

```json
Expand All @@ -369,27 +374,12 @@ Create `~/.opencode/openhax-codex-config.json`:
```

**Settings:**

- `true` (default): Optimize for cost savings
- `false`: Fresh context each turn (higher costs)

**⚠️ Warning**: Disabling caching will dramatically increase token usage and costs.

### Compaction Controls

To mirror the Codex CLI `/compact` command, add the following to `~/.opencode/openhax-codex-config.json`:

```json
{
"enableCodexCompaction": true,
"autoCompactTokenLimit": 12000,
"autoCompactMinMessages": 8
}
```

- `enableCodexCompaction` toggles both the `/codex-compact` manual command and Codex-side history rewrites.
- Set `autoCompactTokenLimit` to have the plugin run compaction automatically once the conversation grows beyond the specified budget.
- Users receive the Codex summary (with the standard `SUMMARY_PREFIX`) and can immediately resend their paused instruction; subsequent turns are rebuilt from the stored summary instead of the entire backlog.

---

## Next Steps
Expand Down
2 changes: 0 additions & 2 deletions lib/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,6 @@ const CONFIG_PATH = getOpenCodePath("openhax-codex-config.json");
const DEFAULT_CONFIG: PluginConfig = {
codexMode: true,
enablePromptCaching: true,
enableCodexCompaction: true,
autoCompactMinMessages: 8,
logging: {
showWarningToasts: false,
},
Expand Down
12 changes: 1 addition & 11 deletions lib/request/codex-fetcher.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
import type { PluginInput } from "@opencode-ai/plugin";
import type { Auth } from "@opencode-ai/sdk";
import { maybeHandleCodexCommand } from "../commands/codex-metrics.js";
import { finalizeCompactionResponse } from "../compaction/compaction-executor.js";
import { LOG_STAGES } from "../constants.js";
import { logRequest } from "../logger.js";
import { recordSessionResponseFromHandledResponse } from "../session/response-recorder.js";
Expand Down Expand Up @@ -93,16 +92,7 @@ export function createCodexFetcher(deps: CodexFetcherDeps) {
return await handleErrorResponse(response);
}

let handledResponse = await handleSuccessResponse(response, hasTools);

if (transformation?.compactionDecision) {
handledResponse = await finalizeCompactionResponse({
response: handledResponse,
decision: transformation.compactionDecision,
sessionManager,
sessionContext,
});
}
const handledResponse = await handleSuccessResponse(response, hasTools);

await recordSessionResponseFromHandledResponse({
sessionManager,
Expand Down
Loading
Loading