opencode-codexsess

OpenCode plugin for CodexSess OpenAI-compatible API (/v1/*).

This plugin keeps setup simple:

• Input baseURL and apiKey
• Verify connection via GET /v1/models
• Auto-register available models in OpenCode as codexsess/<model>
• Enable dynamic context pruning for tool-heavy sessions

What this plugin does

• Uses custom OpenCode provider ID: codexsess.
• Routes requests to your CodexSess endpoint (/v1/chat/completions, /v1/models, etc).
• Registers model keys in OpenCode as:
  • codexsess/<model_id>
• Uses display name format:
  • <model_id> CodexSess
• Runtime plugin automatically strips codexsess/ before sending request to CodexSess API.
• Adds dynamic message pruning before each model call:
  • keeps recent turns untouched
  • compacts old/long tool outputs
  • removes old reasoning/snapshot noise
  • deduplicates repeated tool outputs

Requirements

• Node.js 20+
• Running CodexSess instance
• Valid CodexSess API key (sk-...)

Quick Start

Option A: via npx (after publish to npm)

npx opencode-codexsess

Command di atas langsung menjalankan setup interaktif:

1. Input CodexSess Base URL
2. Input CodexSess API Key
3. Pertanyaan install oh-my-opencode-slim (Y/N)

Option B: local workspace

cd ~/workspaces/codexsess-opencode
npm install
npm run build
# install plugin locally into OpenCode runtime
cd ~/.config/opencode && npm i /home/ricki/workspaces/codexsess-opencode
cd ~/workspaces/codexsess-opencode
npm run setup

Interactive setup will ask:

1. CodexSess Base URL (example: http://127.0.0.1:3061)
2. CodexSess API key (example: sk-xxxx)
3. Whether to also install oh-my-opencode-slim

Then setup will:

• call GET <baseURL>/v1/models
• validate API key + endpoint
• write OpenCode config entries to opencode.json
• migrate existing opencode.jsonc to opencode.json and remove .jsonc
• merge provider.codexsess without removing existing providers/config
• optionally install oh-my-opencode-slim and generate ~/.config/opencode/oh-my-opencode-slim.json with codexsess preset
• enable OpenCode compaction defaults for context efficiency

OpenCode config changes

Setup updates:

• ~/.config/opencode/opencode.json
• ~/.opencode/codexsess-plugin.json

Added/updated fields

• enabled_providers: merged with existing values, ensuring codexsess is included
• model: only set to codexsess/<model> if currently empty
• small_model: only set to codexsess fallback if currently empty
• plugin[] includes opencode-codexsess
• provider.codexsess.options.baseURL (normalized to /v1)
• provider.codexsess.options.apiKey
• provider.codexsess.models from live /v1/models response with key codexsess/<model> and name <model> CodexSess
• Known model limits auto-filled in provider.codexsess.models[*].limit:
  • context = 272000, output = 10000 for gpt-5.4, gpt-5.4-mini, and all *-codex variants (including gpt-5.1-codex-max)
• command shortcuts:
  • /cstats -> context stats + pruning estimate
  • /csweep -> balanced compaction sweep
  • /csweep-hard -> aggressive compaction sweep
• compaction.auto = true
• compaction.prune = true
• compaction.reserved = 8000 (if not already set)
• ~/.opencode/codexsess-plugin.json.contextPruning defaults:
  • enabled = true
  • keepRecentMessages = 24
  • keepRecentToolCalls = 8
  • maxToolOutputChars = 4000
  • maxReasoningChars = 1200
  • dedupeToolOutputs = true
  • dropSnapshotParts = true
  • aiCompaction:
    • enabled = true
    • thresholdChars = 120000
    • cooldownMs = 480000
    • minMessages = 30
    • skipIfModelContextGte = 1000000 (skip auto AI compaction for 1M-context models)

Example

If CodexSess returns:

• gpt-5.2-codex
• gpt-5.2

OpenCode model list will include names:

• key: codexsess/gpt-5.2-codex, name: gpt-5.2-codex CodexSess
• key: codexsess/gpt-5.2, name: gpt-5.2 CodexSess

At runtime, when selected model is codexsess/<model>, plugin rewrites request model to raw <model> before sending to CodexSess API.

Manual Context Controls

• /cstats: show current session context composition + estimated prunable chars.
• /csweep: trigger balanced summarize/compaction.
• /csweep-hard: trigger more aggressive summarize workflow (same summarize endpoint, stricter recommendation).

Notes

• Base URL can be localhost or remote server URL.
• Plugin normalizes base URL automatically to use /v1.
• This package currently assumes local install into OpenCode environment (~/.config/opencode) if not published to npm.
• This plugin does not change CodexSess backend behavior; it only configures OpenCode to use existing CodexSess API.