Codexify

Codexify

Codex-style local tooling for ChatGPT, implemented in Rust.

> 📖 New here? Start with the Wiki — an end-user guide covering installation, every CLI argument, every config option, and how it all works end-to-end. This README is the complete technical reference; the wiki is the friendlier path in.

A local MCP bridge server that lets ChatGPT Web Pro call tools on your machine: read/write files, run shell commands, git operations, and search. Codexify is implemented in Rust with tokio + axum and the official rmcp SDK over Streamable HTTP. It can expose the local MCP endpoint through OpenAI's native Secure MCP Tunnel, without opening an inbound port or publishing a general-purpose URL.

In native-tunnel mode, Codexify listens only on 127.0.0.1, protects the MCP endpoint with a random per-process bearer token, starts OpenAI's official runtime-only tunnel client, and supervises it for the lifetime of the server. The tunnel client makes outbound HTTPS requests to OpenAI and forwards tunnel traffic to the authenticated loopback MCP endpoint. Externally managed tunnels are also supported.

The tool set follows Codex agent contracts for apply_patch, exec_command/write_stdin, view_image, update_plan, clock_curr_time/clock_sleep, project instructions, and skills. Codexify also bridges ChatGPT-native attachments and generated files into the active local project, returns project files as downloadable MCP resources, proxies resource links returned by bridged MCP servers, bounds model-visible tool output, persists task notes and plans, and records project-scoped diff checkpoints.

Codexify can also aggregate other MCP servers. It connects to local stdio servers or remote Streamable HTTP endpoints, keeps automatically imported Codex/plugin tool catalogues private by default, and gives the ChatGPT-side agent a fixed ranked discovery/schema/call surface. Direct exposure and single-dispatcher gateway modes are configurable per upstream.

Architecture

flowchart LR
    ChatGPT["ChatGPT Web Pro"]
    OpenAITunnel["OpenAI Secure MCP Tunnel"]
    TunnelClient["Official OpenAI\ntunnel-client-runtime"]
    Server["Codexify\nMCP Bridge\n127.0.0.1:3000"]
    Tools["Tool Registry"]

    FS["read_file\nwrite_file\nlist_directory\ntree"]
    Ingress["import_host_file"]
    Egress["export_host_file"]
    Search["glob\ngrep"]
    Git["git_status\nshow_diff\ngit_push\ngit_commit\ngit_log"]
    Edit["apply_patch"]
    Exec["exec_command\nwrite_stdin"]
    Agent["view_image\nupdate_plan\nclock_curr_time\nclock_sleep"]
    Env["get_agent_brief\nget_environment\nget_project_doc"]
    Mem["remember\nrecall"]
    Skills["skills_list\nskills_read"]
    ListProjects["list_projects"]
    SetRoot["set_project_root"]
    Bridge["MCP aggregator\n(bridge.rs)"]
    WorkDir[("Active workspace root\nproject, worktree,\nor scratch")]
    HostFiles[("ChatGPT attachments\nand generated files")]
    ArtifactCache[("Bounded immutable\nfile snapshots")]
    State[("~/.codexify\nmemory (per active root)")]
    Bindings[("~/.codexify\nconversation-projects")]
    Scratch[("~/.codexify/scratch\nprivate conversation workspace")]
    Worktree[("Managed Git worktree\nper-conversation checkout,\nswept on startup")]
    ExecSessions[("Conversation exec sessions\n(in memory, idle-reaped)")]
    DiffRefs[("Git refs/codexify/diff\nproject-open + last-diff")]
    DiffUI["MCP App diff card\nui://codexify/diff/v3/mcp-app.html"]
    SkillDirs[(".agents/skills\n.codex/skills\n.claude/skills")]
    CodexCfg[("$CODEX_HOME\nconfig.toml")]
    CodexCli["optional Codex CLI\nmcp list/get --json"]
    Upstream[("Upstream MCP servers\nstdio / Streamable HTTP")]

    ChatGPT |"connector calls"| OpenAITunnel
    TunnelClient |"outbound HTTPS"| OpenAITunnel
    TunnelClient |"loopback HTTP\n/mcp"| Server
    Server -- "Streamable HTTP\n(MCP Protocol)" --> Tools

    Tools --> FS
    Tools --> Ingress
    Tools --> Egress
    Tools --> Search
    Tools --> Git
    Tools --> Edit
    Tools --> Exec
    Tools --> Agent
    Tools --> Env
    Tools --> Mem
    Tools --> Skills
    Tools -.->|"multi-project mode"| ListProjects
    Tools -.->|"multi-project mode"| SetRoot
    Tools --> Bridge

    FS --> WorkDir
    HostFiles --> Ingress
    Ingress --> WorkDir
    WorkDir --> Egress
    Egress --> ArtifactCache
    Server |"resource_link / resources/read"| ArtifactCache
    Search --> WorkDir
    Shell --> WorkDir
    Edit --> WorkDir
    Exec --> WorkDir
    Agent --> WorkDir
    Env --> WorkDir
    Mem --> State
    Skills --> SkillDirs
    ListProjects -.->|"selector"| SetRoot
    SetRoot --> Bindings
    SetRoot -.->|"withoutProject"| Scratch
    Scratch -.->|"active root"| WorkDir
    SetRoot -.->|"worktree mode"| Worktree
    Worktree -.->|"active checkout"| WorkDir
    Exec --> ExecSessions
    Git --> DiffRefs
    Git -.-> DiffUI
    SetRoot -.->|"selects"| WorkDir
    CodexCfg -.->|"project candidates"| ListProjects
    CodexCfg -.->|"auto-import"| Bridge
    CodexCli -.->|"plugin/effective MCPs"| Bridge
    Bridge --> Upstream

Dotted edges are conditional: list_projects and set_project_root appear only in [multi-project mode](#multi-project-mode). The first discovers selectable candidates from Codex's project trust table plus optional local metadata; the second binds this conversation to a project, managed Git worktree, or private scratch workspace. Independently, the aggregator [auto-imports](#automatic-discovery-from-codex) compatible stdio and Streamable HTTP MCP servers directly from Codex's config.toml, then uses the Codex CLI when available to add plugin-provided servers before applying any codexify.config.json overlays.

Quick start

Install the latest release

Linux and macOS:

curl -qfsSL https://codexify.dev/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://codexify.dev/install.ps1 | iex"

The installer downloads the latest release archive, verifies it against the published SHA-256 checksums, and replaces the executable under ~/.codexify/bin. On Unix it adds that directory to every recognized existing shell profile and creates the active shell's profile when needed. On Windows it updates the persistent user PATH. The macOS installer removes the executable's com.apple.quarantine attribute after installation. It also installs and starts the per-user Codexify background service. Set CODEXIFY_SKIP_SERVICE=1 in the installer process to install only the executable and PATH entry.

Interactive setup (recommended for a first install)

Run the guided setup from an installed binary:

codexify quickstart

Or run it directly from a source checkout:

cargo run --release -- quickstart

The wizard asks which project directory ChatGPT may access and whether that directory is one project or a multi-project access root. It then walks through creating an OpenAI Secure MCP Tunnel, entering the tunnel ID and runtime API key, and creating the matching ChatGPT developer-mode connector. Advanced policies, including optional per-conversation authorization, are configured manually rather than presented during first-run onboarding. The relevant OpenAI and ChatGPT links are printed together with the exact connection values to use.

The runtime key is entered without terminal echo and stored in a dedicated per-tunnel file under ~/.codexify/openai-tunnel/credentials/. On Unix, the wizard restricts the credential directory and file to the current user. The wizard writes ~/.codexify/codexify.config.json by default; that file receives the absolute workDir, a file: reference to the runtime key, and the selected project mode; unrelated JSON settings are preserved. When the background service is installed, quickstart updates its definition and restarts it with this config. Otherwise, the wizard offers to start Codexify in the current terminal.

When an existing config already contains conversationAuthToken, quickstart preserves it, restricts the config file to the current user on Unix, and prints the one-line instruction required to authorize a chat. It does not offer to enable or rotate this advanced feature. Keep a token-bearing config out of version control and do not share it.

Set CODEXIFY_CONFIG=/path/to/codexify.config.json or use codexify quickstart --config /path/to/codexify.config.json to update a different config file. --work-dir /path/to/project changes the directory initially shown by the wizard.

Manual native OpenAI tunnel setup

1. Create or obtain a tunnel ID in OpenAI Platform tunnel settings.
2. Create a restricted runtime API key whose principal has Tunnels Read + Use for that tunnel. Keep tunnel-management/admin credentials separate.
3. Add the tunnel to ~/.codexify/codexify.config.json:

``json { "workDir": "/absolute/path/to/your/project", "openaiTunnel": { "tunnelId": "tunnel_0123456789abcdef0123456789abcdef", "apiKeyRef": "env:CONTROL_PLANE_API_KEY" } } ``

1. Put the runtime key in the referenced environment variable and start Codexify:

``bash export CONTROL_PLANE_API_KEY='...' cargo run --release -- --work-dir /path/to/your/project ``

On first use, Codexify downloads the pinned runtime-only build of OpenAI's official tunnel-client, verifies the archive against the per-platform SHA-256 embedded in this Codexify build, and installs it under ~/.codexify/openai-tunnel/. Codexify reports ready only after the runtime's /readyz check succeeds and its metrics show a successful control-plane poll. The runtime-only binary exposes loopback /healthz, /readyz, and /metrics endpoints; it intentionally does not include the full client's admin UI.

To use a preinstalled official client, set openaiTunnel.clientPath or pass --openai-tunnel-client /path/to/tunnel-client-runtime. Codexify checks the binary's version surface and required flags before starting it.

Local endpoint or externally managed tunnel

cargo run --release -- --work-dir /path/to/your/project

Without openaiTunnel, the server listens on 0.0.0.0:3000, serves MCP at /mcp, and serves /health. This mode is intended for local clients or an explicitly configured reverse proxy/tunnel. Do not publish it without authentication and network-level access controls.

To reuse one server across several independent projects, point it at their common parent and enable multi-project mode:

cargo run --release -- --work-dir /path/to/projects --multi-project

Here --work-dir is an access root, not the active project. In ChatGPT, call set_project_root directly when the exact relative/absolute path, an HTTPS/SSH Git repository URL ending in .git, or a supported GitHub repository, branch, pull-request, or commit URL is known. Repository URLs reuse an unambiguous matching checkout already below the access root, or run git clone in the configured project clone directory before binding. GitHub branch, PR, and commit URLs select their exact targets without switching an unrelated source checkout. When per-conversation setup is enabled and the intended project is ambiguous, the setup card loads list_projects into a searchable chooser and keeps Chat without a project at the top; that choice creates a private scratch workspace outside the access root. Codexify keys the resulting project or scratch binding from ChatGPT's _meta["openai/session"] conversation identifier and persists it outside the repository, so later turns in the same chat recover the active workspace after an MCP reconnect or Codexify restart. A new chat gets a new binding and an existing chat cannot switch choices. Clients that do not provide openai/session fall back to a one-time MCP transport-session binding; their scratch directory is removed when that session ends.

Optional per-conversation authorization

Set a high-entropy authentication token manually in the config. The token itself, not a digest of another secret, must look like a SHA-256 value: exactly 64 lowercase hexadecimal characters. For example:

python -c 'import secrets; print(secrets.token_hex(32))'

{
  "conversationAuthToken": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

When this key is present, Codexify rejects every ordinary tool call until the current chat presents that exact token once. A successful check authorizes only the stable ChatGPT conversation that made the call. The project-aware initialization brief is withheld until authorization succeeds; the gate response then directs the client to load it with get_agent_brief. The same successful setup result includes the current project/scratch state, running Codexify version, a bounded latest-release check, and connector-schema freshness data, so the model does not need follow-up status calls.

The MCP wire surface deliberately calls this authorization tool setup and its token parameter ref. ChatGPT can otherwise falsely classify a token-looking connector call as an unsafe secret leak and refuse to make the call. Keeping the actual token in a SHA-256-shaped format and using the innocuous setup(ref) names avoids that false positive. ref is the authentication token, remains secret, and is submitted verbatim; no digest transformation is applied.

The advertised setup description contains a connector version marker and its schema includes an optional connectorVersion echo field. A current connector copies that marker into the call. After a Codexify upgrade, ChatGPT may still call the cached older schema, which omits the field; the result then warns that the connector tools should be refreshed. This remains backward compatible because connectorVersion is optional in the running server's validator.

The setup component checks for a newer release through gh api first, with a strict 2-second timeout, and falls back to the unauthenticated GitHub releases API with a 2-second timeout. Successful results are cached for 5 minutes and failures for 30 seconds. Its compact Codexify row always exposes Check for updates; that app-only action bypasses the cache and updates the row without rerunning the conversation-authorization flow. A known newer release adds a row-local Upgrade action that invokes the ordinary verified self_update path only after the user clicks it.

In multi-project mode an unbound conversation also receives a searchable project chooser before those status controls. The component calls list_projects after its app bridge is ready, debounces server-side searches, and calls set_project_root only for the row or scratch option the user selects. A successful receipt replaces the chooser with the active direct path, managed worktree plus source checkout, or private scratch path.

After rendering the setup result, the component starts the app-only doctor tool asynchronously, so the model can continue project selection and get_agent_brief without waiting for diagnostics. A healthy automatic result remains hidden; warnings are summarized compactly and failures expand into colored structured checks. Warning and failure states expose Autofix, which sends the findings to ChatGPT for diagnosis and repair rather than executing remediation inside

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: devnoname120
• Source: devnoname120/codexify
• License: MIT
• Homepage: https://codexify.dev/

Install and usage instructions live in the source repository linked above.