ChatGPT Local Coder

Turn ChatGPT web into a local coding agent — files, shell, git, patches, 40+ MCP tools.

Quick Start · Connect ChatGPT · Tools · Tunnel · Troubleshooting · Tiếng Việt

ChatGPT Local Coder is a self-hosted MCP server for local coding, with task permissions, approval requests, file review/undo and Git/GitHub tools.

Workbench branch: see setup, behavior and known limits. This is an initial implementation, not complete Codex parity. New tasks default to Ask + workspace-only. An OS process sandbox is not implemented; shell/Git/GitHub require explicitly disabling workspace-only scope. MCP authentication is now required; ChatGPT uses OAuth with local consent.

No desktop app. No vendor lock-in. Run one Node process on your PC, expose it through a tunnel, and code from ChatGPT in the browser.

┌─────────────────┐     HTTPS      ┌──────────────────┐     localhost     ┌─────────────────────┐
│   ChatGPT Web   │ ─────────────► │  Tunnel (opt.)   │ ────────────────► │  chatgpt-local-coder │
│ Developer Mode  │                │ OpenAI / CF      │      :3000/mcp    │  40+ MCP tools       │
└─────────────────┘                └──────────────────┘                   └──────────┬──────────┘
                                                                                    │
                                         ┌──────────────────────────────────────────┼──────────┐
                                         ▼                    ▼                    ▼          ▼
                                   Filesystem              Shell + Git         Background    Project
                                   read/write/patch        status/diff/commit   processes     context

✨ Why this project

Built for ChatGPT Developer Mode with batched inspection, cursor-based process output, honest tool annotations and a local Workbench dashboard.

Related MCP server: chatgpt-local-coder

🚀 Quick Start

Requirements: Node.js 18+, npm, Git (optional, for git tools)

git clone https://github.com/hoangcoderr/chatgpt-local-coder.git
cd chatgpt-local-coder
copy .env.example .env          # edit WORKSPACE_PATH
npm install
npm run build
.\start.ps1

Server runs at http://localhost:3000 — health check: http://localhost:3000/health

git clone https://github.com/hoangcoderr/chatgpt-local-coder.git
cd chatgpt-local-coder
cp .env.example .env
npm install && npm run build
npm start

🔌 Connect ChatGPT

1. Enable Developer Mode

1. Open ChatGPT → Settings → Apps & Connectors

2. Under Advanced, enable Developer mode

2. Expose your server (pick one tunnel)

See Tunnel options below. You need a public HTTPS URL pointing to http://localhost:3000/mcp.

3. Create a connector

1. Settings → Connectors → Create

2. Fill in:

3. Create → verify tools appear in the list

4. Use in chat — must tag the connector

Every message that should use local tools must include the connector. If you skip this, ChatGPT only uses built-in tools, may show "Looking for available tools" / "Đang tìm các công cụ có sẵn", then "Error in message stream" / "Lỗi trong luồng tin nhắn" — with no error in server logs (the MCP server was never called).

How to tag (pick one):

1. Before sending: New chat → + (tools) → More → enable Local Coder (connector stays on for that chat).

2. In the message: type @ and choose Local Coder (or your connector name) so it appears as a pill/chip above the input.

Then send your prompt. You should see tool permission prompts or MCP activity — not a dead stream with no server log.

Example prompts (after tagging):

• "Read package.json and explain the dependencies"

• "Run npm test and fix any failures"

• "Find all TODO comments with grep and summarize"

Tip: After server updates or restarts → Refresh the connector and start a new chat (re-tag the connector).
Avoid clicking "Always allow" on permission popups — it can reset the MCP session. Configure permissions in Settings → Apps instead.

🌐 Tunnel options

Option A — OpenAI Secure MCP Tunnel (recommended)

Stable tunnel ID — connector URL never changes.

# Terminal 1
.\start.ps1 -Force

# Terminal 2 — first time only
.\openai-tunnel-init.bat    # enter tunnel_id + Runtime API key from OpenAI Platform

# Every time after
.\openai-tunnel.bat

Get credentials: OpenAI Platform → Tunnels

In ChatGPT Connectors: Connection type → Tunnel → paste your tunnel_… ID.

Option B — Cloudflare Quick Tunnel

Free, but URL changes on every restart (update connector each time).

# Terminal 1
.\start.bat

# Terminal 2
.\tunnel.bat    # copy https://….trycloudflare.com into connector URL

Install cloudflared: winget install Cloudflare.cloudflared

🧰 Tools

40+ tools with structured JSON responses { ok, tool, summary, data }.

Onboarding (call these first)

Filesystem

Shell

Git

Claude Code ↔ MCP mapping

⚙️ Configuration

Copy .env.example → .env:

PORT=3000
WORKSPACE_PATH=C:\Users\You\projects\my-app
WORKBENCH_DEFAULT_MODE=ask
SHELL_TIMEOUT=120
MCP_SESSION_RECOVERY=true

# OpenAI Secure Tunnel (optional)
OPENAI_TUNNEL_ID=
OPENAI_TUNNEL_API_KEY=

New tasks default to Ask + workspace-only. Use the Workbench dashboard to change scope and approval mode; changing tool annotations does not grant permission.

🏗️ Architecture

src/
├── index.ts                 # Express + MCP session manager
├── server-factory.ts        # Tool registration
├── lib/
│   ├── mcp-session-manager.ts   # Session recovery, TTL
│   ├── patch.ts             # apply_patch engine
│   └── persistent-shell.ts  # Stateful shell
└── tools/
    ├── filesystem.ts        # 18 tools
    ├── shell.ts             # 8 tools
    ├── git.ts               # 11 tools
    └── context.ts           # agent_status, project_context

• Transport: MCP Streamable HTTP (/mcp and /)

• Session: Stateful with auto-recovery when ChatGPT holds a stale session ID

• Output: Structured JSON from every tool

🧪 Development

ChatGPT web performance

The default slim profile includes inspect_code for batched reads/searches with path rules, and cursor-based background output. SSE connections no longer block subsequent tool calls. See design, examples and rollout.

Run npm run test:chatgpt for the isolated HTTP/SSE and workflow regression tests.

npm run build          # compile TypeScript
npm test               # patch + tool unit tests
npm run dev            # watch mode (tsx)
node scripts/test-mcp-session.mjs   # integration test (server must be running)

🔒 Security

Full access is an explicit task setting. OAuth linking requires local consent, and the admin API requires its own token. Workspace-only currently restricts file tools and blocks arbitrary processes; it is not an OS sandbox. See limitations before enabling unrestricted commands.

• .env and secrets are gitignored

• Audit log: .mcp-audit.log (optional, configurable)

• Use on a trusted network / personal machine only

🩺 Troubleshooting

See also AGENTS.md for agent onboarding and apply_patch format.

📚 References

• Model Context Protocol

• MCP TypeScript SDK

• ChatGPT Apps SDK

• OpenAI Secure MCP Tunnel

📄 License

MIT — use freely, attribution appreciated.

⭐ Support

If this saves you time, star the repo — it helps others find it.

🇻🇳 Tiếng Việt

ChatGPT Local Coder biến ChatGPT web thành agent code trên máy bạn qua MCP.

git clone https://github.com/hoangcoderr/chatgpt-local-coder.git
cd chatgpt-local-coder
copy .env.example .env
npm install && npm run build
.\start.ps1                    # terminal 1
.\openai-tunnel.bat            # terminal 2 (tunnel cố định)

ChatGPT: Settings → Connectors → tạo connector → chọn tunnel → Refresh → chat mới.

Bắt buộc tag connector mỗi chat: Chat mới → + → More → bật connector, hoặc gõ @ + tên connector trong ô chat. Nếu không tag, ChatGPT báo "Đang tìm các công cụ có sẵn" rồi "Lỗi trong luồng tin nhắn" — server không có log lỗi vì MCP chưa được gọi.

WORKSPACE_PATH: đặt đúng thư mục project (không phải thư mục chatgpt-local-coder). Server tự đọc CLAUDE.md / AGENTS.md giống Claude Code.

Lưu ý: Không bấm "Luôn cho phép" trên popup — cấu hình quyền ở Settings → Apps. Sau khi restart server: Refresh connector + mở chat mới + tag lại connector.

Chi tiết cho AI agent: AGENTS.md

MCP_Plugins_With_ChatGPTWeb