Codex Context Studio

🧠 Context Control Panel for Codex
_{Make Codex's context visible, locatable, and precisely manageable — like memory.}

Features · Architecture · Install · FAQ

English · 中文

---

⚡ In One Line

This project lets you see Codex's context consumption, what's retained after compression, and edit it yourself. It also lets you replace Codex's system prompt to break through Codex's limitations, and replace Codex's compression prompt for better compressed output.

---

🎯 Core Features

🔬 Context Visualization — See Inside Codex's Brain

View Codex's context by role, check token usage per turn, and see when prompts are injected.

✂️ Context Management — Take Over Codex's Memory

Chat with a dedicated secondary model to analyze, edit, compress, and manage the main Codex's context. You can plug in a cheap secondary model.

📈 Usage Panel — How Much Did This Session Cost?

View token consumption, cache hit rate, and estimated cost across your Codex session.

🔀 Prompt Replacement — Rewrite Codex's Default Prompts

Replace Codex's system prompt and native compression prompt for jailbreaking and better compression quality.

🔌 Local Proxy — Transparent, Non-Invasive

No Codex source code changes, no official tools replaced. Sits in the middle as a local proxy, compatible with all native features.

---

📸 Screenshots

Context Map & Secondary Model Chat

Context Compression Result

Prompt Replacement

Usage Panel

---

🏗️ Architecture

flowchart LR
    CD["Codex CLI / Desktop"]
    PX["Responses Proxy\n:8787"]
    WEB["Web Backend\n:8765"]
    FE["React Workbench"]
    OAI["OpenAI API / Upstream Model"]

    CD -- "POST /v1/responses" --> PX
    PX -- "Rebuilt request" --> OAI
    OAI -- "SSE stream" --> PX
    PX -- "SSE stream" --> CD

    FE -- "HTTP edit/settings" --> WEB
    WEB -- "HTTP proxy control" --> PX
    PX -. "WebSocket realtime events" .-> FE

Loading

How It Works:

Every Codex request follows the same path — there is no "pass-through if unedited" branch:

flowchart LR
    A["Codex sends request"] --> B["cursor diff"] --> C["Update transcript"] --> D["Rebuild input"] --> E["Forward upstream"]

Loading

• Transcript is the single source of truth: what users see in the workbench, edit, and what ultimately gets sent upstream
• Without edits, the rebuilt input is naturally equivalent to the original Codex input
• With edits, upstream receives the edited transcript + new content from the current turn
• During compression, Codex's native compression prompt is replaced with a custom version, and the result is written back to the transcript

---

🚀 Quick Start

1. Install

Download and run the latest Windows installer from Releases.

2. Enable CLI Proxy

codex ctx proxy on      # Enable proxy
codex                   # Use Codex normally
codex ctx proxy status  # Check status
codex ctx proxy off     # Disable proxy

3. Desktop Support

codex ctx desktop on      # Enable Desktop mode
codex ctx desktop status  # Check status
codex ctx desktop off     # Disable

Note

Enabling either persistent proxy mode or Desktop mode temporarily writes the selected Studio provider, hook, and notify entries to local Codex configuration. The matching off command restores the previous configuration.

---

🛠️ Development

The source checkout uses an explicit dev profile. Every development control command ends in dev; installed EXE commands never do. See runtime layout and external files for the full command matrix and directory boundaries.

# Register and control the source checkout
npm run ctx:install:dev
codex ctx desktop on dev
codex ctx desktop status dev
codex ctx desktop off dev
codex ctx desktop uninstall dev

# Install dependencies
npm install
npm run setup:python

# Run the full local flow
npm run codex

# Run only the context window
npm run window

# Run checks
npm run typecheck
npm test

# Build Windows installer
npm run package:win

---

❓ FAQ

Is this a Codex plugin?

No. Codex Context Studio is a local context layer around Codex, implemented through proxy technology.

Will it break the cache?

Compression is not a frequent event. After compression, it only recalculates once, which is more cost-efficient than carrying useless context. In practice, cache hit rate only drops by 5–10%.

Why not just rely on auto-compaction?

Compatible with native compression. The project also helps replace compression prompts — we've built more precise, targeted compression features.

Who is this for?

People who want better control over context, have their own ideas about compression, or want to modify Codex's prompts.

---

_{GPL-3.0 · Made with ❤️ for Codex power users}