CodeLocal / codex-mcp

Remote MCP coding bridge for ChatGPT/Codex.

ChatGPT / Codex
    | MCP over HTTPS + OAuth
    v
Railway gateway
    | authenticated WebSocket
    v
CodeLocal client on your machine
    | local workspace tools
    v
PROJECT_ROOT

The model remains the reasoning layer. CodeLocal provides local filesystem access, selective retrieval, semantic code intelligence, Git, diagnostics/tests, guarded shell/process execution, approvals, routing and observability.

Current version

1.0.0-preview.1

This preview is intentionally conservative: sensitive paths remain blocked, risky shell operations require local approval, and OS-level sandboxing/production device-pairing are not claimed as complete yet.

Major capabilities

Workspace + retrieval

• .gitignore-aware listing/search
• targeted reads of ignored dependency/generated files when explicitly requested
• sensitive-path policy independent from .gitignore
• binary detection
• file metadata, SHA-256 hash and mtime
• line-range reads
• conflict-safe write/edit with expectedHash
• scoped AGENTS.md/repo instructions

Dependencies

• inspect installed Node dependency metadata
• targeted dependency file reads
• dependency-only search

Semantic code intelligence

TypeScript/JavaScript semantic index backed by the TypeScript compiler API:

• symbols
• definitions/declarations
• references
• callers/callees
• import/export graph
• TypeScript diagnostics

Other languages continue to work through filesystem/search/shell/toolchain commands; dedicated semantic backends can be added progressively.

Tests + Git

• detect likely test/lint/typecheck/build commands
• find likely related tests
• run affected test command
• git status
• git diff
• git log
• git show
• git blame
• per-file history

Runtime

• guarded local shell
• incremental process output cursors
• real-time stdout/stderr mirrored to the local terminal
• process list/stdin/kill
• local approval prompts for package changes, Git writes, migrations, network commands and recursive deletes
• hard blocks for obvious credential/system/disk escape commands unless explicitly unsafe mode is enabled

Multi-device / multi-workspace routing

A client registers:

deviceId + workspaceId + workspaceName

MCP sessions can use:

list_devices
list_workspaces
select_workspace
workspace_info

If exactly one workspace is online it is selected implicitly. If more than one is online the model must select one explicitly.

Server

Production test server currently deployed on Railway:

https://codex-mcp-production.up.railway.app/mcp

ChatGPT -> server authentication uses OAuth.

Local client -> server authentication currently uses DEVICE_TOKEN. This is still preview-level device auth; production per-device pairing/rotation is a later hardening step.

Install client

git clone https://github.com/0xmarkhydra/codex-mcp.git
cd codex-mcp
npm install

For an existing clone:

cd ~/Documents/codex-mcp
git pull
npm install

Run client against a project

Example:

PROJECT_ROOT="$HOME/Desktop/BIDDI" \
SERVER_URL="wss://codex-mcp-production.up.railway.app/client" \
DEVICE_TOKEN="YOUR_DEVICE_TOKEN" \
CODELOCAL_ALLOW_SHELL=1 \
CODELOCAL_DEVICE_ID="macbook-pro" \
CODELOCAL_WORKSPACE_ID="biddi" \
CODELOCAL_WORKSPACE_NAME="BIDDI" \
npm run client

Useful optional variables:

CODELOCAL_APPROVAL_MODE=prompt   # default: prompt; other supported preview values: deny, auto
CODELOCAL_ALLOW_DANGEROUS=0      # default; do not enable casually
CODELOCAL_MIRROR_PROCESS_OUTPUT=1
CODELOCAL_LOG_LEVEL=info

Expected startup logs are JSON structured events such as:

client.started
client.connecting
client.registered

When ChatGPT runs a command, stdout/stderr also appears locally with a process prefix.

ChatGPT setup

Create/connect the developer MCP app with:

https://codex-mcp-production.up.railway.app/mcp

Authentication: OAuth.

After a tool/schema update, reconnect/refresh the MCP app so ChatGPT discovers the latest tool list.

Recommended first prompt

Use CodeLocal.
Inspect project_info and repo instructions first.
Analyze the architecture before editing.
Use semantic/reference tools and targeted reads rather than reading the entire repository.
Run appropriate diagnostics/tests, then show git diff.
Do not perform risky operations unless needed.

Retrieval policy

.gitignore controls normal retrieval/indexing, not security.

Normal source
  -> list/search normally

Ignored dependency/build/cache
  -> excluded from normal scans
  -> targeted read/search allowed when needed

Sensitive credentials/secrets
  -> blocked independently of .gitignore

Typical blocked sensitive paths include .env* (except templates/examples), .ssh, .aws, .gnupg, private key files and obvious credential files.

Safety notes

The current client enforces workspace path boundaries for filesystem tools and applies command-policy checks for shell commands. A shell process is still a local OS process, so this preview should not be described as a complete native OS sandbox.

Do not expose device credentials publicly. Rotate the preview DEVICE_TOKEN before broader use.

What is still not claimed as production-complete

• native OS sandbox parity across macOS/Linux/Windows
• fully persistent per-device pairing/revocation database
• true PTY resize/control parity for all interactive terminal applications
• dedicated LSP daemon integrations for every language
• durable server state across replicas/restarts

These are intentionally separated from the already-working coding loop rather than faked behind tool names.

Coding loop target

understand task
-> project_info + instructions
-> semantic symbols/references/import graph
-> targeted file/range/dependency reads
-> diagnostics/build/tests
-> edit with hash/conflict protection
-> re-run diagnostics/tests
-> git diff/history
-> explain result

See ROADMAP.md for design rationale and hardening work.