Skip to content

How It Works

Jump to bottom
Paul edited this page Sep 9, 2026 · 4 revisions

How It Works

This page traces Codexify end-to-end: how a request from ChatGPT reaches a tool on your machine, and everything the server does around each call. If you only read one "under the hood" page, read this one.

The picture

flowchart LR
    ChatGPT["ChatGPT Web\n6 Astra Pro"]
    Tunnel["OpenAI Secure MCP Tunnel"]
    Client["Official OpenAI\ntunnel-client-runtime\n(supervised)"]
    Server["Codexify\nMCP Bridge\n127.0.0.1:3000"]
    Tools["Tool Registry"]
    WorkDir[("Active project root")]
    State[("~/.codexify\nplan + notes")]
    Upstream[("Bridged MCP servers")]

    ChatGPT <-->|"connector calls"| Tunnel
    Client <-->|"outbound HTTPS"| Tunnel
    Client <-->|"loopback HTTP /mcp\n+ per-process bearer"| Server
    Server --> Tools
    Tools --> WorkDir
    Tools --> State
    Tools -.->|"if configured"| Upstream
Loading

The key property: traffic is outbound-only. Codexify listens on 127.0.0.1. The tunnel client dials out to OpenAI over HTTPS and forwards tunnel traffic back to the authenticated loopback endpoint. No inbound port is opened, and there's no public URL.

1. Startup

When you run codexify --work-dir …, before it accepts any traffic the server:

  1. Reads config. Loads codexify.config.json (or the built-in defaults if missing) and applies CLI-flag overrides. The startup banner reports the effective settings.
  2. Resolves the mode. Single-project (default), multi-project (--multi-project), and native-tunnel vs legacy/external — see below.
  3. Discovers MCP upstreams. Reads $CODEX_HOME/config.toml (read-only) for [mcp_servers.*], optionally enriches via codex mcp list/get --json, then applies your mcpServers overlays. Each upstream is connected and its tools listed. The banner names every one — including failures. See Bridging MCP Servers.
  4. Installs/verifies the tunnel runtime (native mode only). Downloads the pinned official client if absent, checks it against an embedded SHA-256, and starts it. The server reports ready only after /readyz passes and a control-plane poll succeeds.
  5. Sweeps stale worktrees (multi-project). Removes old, clean, unreferenced managed worktrees beyond keepCount. See Worktree Isolation.

2. A conversation connects (the initialize handshake)

When ChatGPT (or any MCP client) opens a session, the server returns an initialize response. Its instructions field is where Codexify layers Codex's operating brief, in Codex's own order, each part outranking the one above it:

  1. The agent brief — how to behave (edit carefully, apply_patch over rewrites, respect the dirty-worktree rules, keep a plan, report concisely). Ported from Codex's own prompt.
  2. The environment — OS, shell, work directory, command policy.
  3. Saved state — the plan and notes from earlier work, if any. See Context and Memory.
  4. The skill catalogue — what this project and user know how to do, if any skills are installed. See AGENTS and Skills.
  5. AGENTS.md — the project speaking for itself, behind a --- project-doc --- marker.

Because instructions is rebuilt per session, editing AGENTS.md or adding a skill takes effect on the next connection — no restart needed.

Important: no client is obliged to show instructions to its model, and ChatGPT Web isn't reliable about it. That's why get_agent_brief returns the identical string on demand. Opening a chat with "Call get_agent_brief and follow it for the rest of this chat" is the reliable way to onboard. See Connecting to ChatGPT.

Connector-schema reload tracking

When an identifiable ChatGPT caller requests tools/list, Codexify records the exact running package version that served the schema. The record is keyed by a SHA-256-derived caller identity from openai/subject plus optional openai/organization, then scoped to the native tunnel ID or external HTTP work-directory/port endpoint. It therefore spans conversations for the same ChatGPT caller and connector while separating accounts, organizations, and Codexify endpoints. Anonymous discovery is deliberately not attributed.

Only the version string is stored, under ~/.codexify/connector-schemas/<endpoint-hash>/<caller-hash>, with private directory permissions on Unix and atomic replacement. The in-memory observation remains usable even if persistence fails. This is UI bookkeeping, not authorization.

The setup app calls the private setup_status helper with the version embedded in that conversation's setup card. Codexify can then distinguish:

  • the running server, recorded connector schema, and conversation card all current;
  • a connector whose last tools/list version is older than the server, requiring ChatGPT's Refresh control; and
  • a connector already refreshed to the server version while the current conversation/card remains older, requiring a new conversation.

Polling setup_status never counts as a schema reload; only tools/list does.

3. A tool call arrives

For each tool call, the server:

  1. Identifies the owner. For ChatGPT calls carrying _meta["openai/session"], work is scoped to that hashed conversation identity — so bindings, memory, diff checkpoints, and exec_command sessions survive the connector swapping transports mid-chat. Clients without that metadata fall back to a per-transport-session scope.
  2. Resolves the active project root. --work-dir in single-project mode; the conversation's selected root in multi-project mode. Until a root is bound in multi-project mode, project-scoped tools are unavailable and say why.
  3. Guards the path. Every filesystem tool resolves paths through a guard that rejects anything outside the active project root — after canonicalization, so .. and symlinks can't escape.
  4. Enforces policy. exec_command runs unrestricted by default. When exec.mode is "allowlist", every command position in the shell string must appear in the complete exec.extraAllowedCommands list; command substitution is rejected. Output is bounded per the output block.
  5. Initializes diff state (first project-scoped call). Captures the checkout as the agent first sees it, before any write — the immutable project-open baseline. See Diff Checkpoints.
  6. Runs the tool, bounds the result, and appends a truncation notice when it hit a cap.
  7. Records an audit event if --audit is set — hashes, timings, sizes, redacted argument shape. See Audit Logging.

4. Bounded output

Any tool that could return unbounded text stops at a budget and says so on its last line, naming the argument that continues:

(showing lines 1-1000 of 4820 — call again with offset=1000 for the rest)

That last line matters as much as the cap — silent truncation reads as "that was the whole file", which is worse than no cap. read_file has a byte ceiling as well as a line one (a minified bundle is one line, megabytes long). exec_command and grep are bounded too, ported that way from Codex.

5. State that outlives the chat

ChatGPT's window is smaller than most real tasks, and a new chat starts blank. Codexify keeps what's expensive to rediscover:

  • remember writes one keyed note; recall returns the notes plus the current plan; update_plan persists the plan itself.
  • State lives in ~/.codexify/projects/<name>-<hash>/memory.json, keyed by the absolute project root — never inside your repo.
  • In single-project mode, the saved plan and notes are already in front of a new conversation via instructions. In multi-project mode they arrive from get_agent_brief after the project is selected.
  • In multi-project mode, a setup-card continuation can bind a new ChatGPT conversation to the exact previously recorded checkout, managed worktree, or persistent scratch root through set_project_root.resumePath. Because the absolute root is unchanged, the same plan/notes and dirty filesystem state remain available. Chat history, resident command sessions, and conversation-keyed diff checkpoints do not transfer.

Full detail in Context and Memory.

The three connection modes

Mode Binds Endpoint Auth When
Native OpenAI tunnel 127.0.0.1 only routed via tunnel random per-process bearer (loopback hop); /readyz gate Recommended. No public URL, no inbound port.
Legacy / external 0.0.0.0:3000 /mcp, /health you provide it (proxy, --api-key) Local clients, or an explicitly authenticated reverse proxy/tunnel.
Multi-project (either of the above) same per-conversation project binding One server, many repos beneath an access root.

Native and multi-project compose — you can run --multi-project behind the native tunnel. What multi-project changes is project selection, not the transport. See Multi-Project Mode and Connecting to ChatGPT.

A full example, start to finish

  1. You run codexify --work-dir ~/code/myapp with an openaiTunnel block configured.
  2. Codexify verifies/starts the tunnel client, connects any bridged MCP servers, and reports ready.
  3. In ChatGPT (Developer mode), you enable the connector for that tunnel and open a chat: "Call get_agent_brief and follow it for the rest of this chat. Task: fix the failing test in auth.rs."
  4. ChatGPT calls get_agent_brief, receives the environment + AGENTS.md + any saved plan, and starts working the way Codex would.
  5. It calls grep, read_file, apply_patch, exec_command — all pinned to ~/code/myapp, all bounded, all optionally audited.
  6. It calls show_diff to show you exactly what it touched, and git_commit / git_push when you approve.
  7. You close the chat. The plan and notes persist. In single-project mode a new chat receives them through the brief; in multi-project mode it first selects a workspace or resumes the exact recorded one, then calls get_agent_brief/recall.

See also

Repository · Releases · Report an issue · MIT License

Codexify

Getting started

Reference

How it works

Multi-project

Extending

Operations

Clone this wiki locally