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 that gives ChatGPT (and any MCP client) full access to your machine — read and edit code, run npm test, manage git, apply unified diffs, and explore projects with glob / grep.

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

	ChatGPT alone	+ ChatGPT Local Coder
Edit your repo	❌	✅ `apply_patch`, `edit_file`, `multi_edit`
Run tests / builds	❌	✅ `run_command`, `start_process`
Git workflow	❌	✅ `git_status`, `git_commit`, `git_push`, …
Explore codebase	Limited	✅ `glob`, `grep`, `list_directory`
Full disk access	❌	✅ Any path on your machine
Session recovery	—	✅ Auto-recover after server restart

Built for ChatGPT Developer Mode with optimized tool annotations (fewer permission popups) and OpenAI Secure MCP Tunnel support (stable URL, no connector re-wiring every restart).

🚀 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

macOS / Linux

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

Open ChatGPT → Settings → Apps & Connectors
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

Settings → Connectors → Create
Fill in:

Field	Value
Name	`Local Coder`
Description	`Local coding agent. First call agent_status + project_context. Use glob/grep to explore, apply_patch to edit, run_command for shell.`
URL	Your tunnel HTTPS URL (e.g. `https://…` or OpenAI Tunnel ID)
Authentication	None

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):

Before sending: New chat → + (tools) → More → enable Local Coder (connector stays on for that chat).
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)

Tool	Description
`agent_status`	Permissions, workspace roots, audit log
`project_context`	Reads AGENTS.md, README, CLAUDE.md, configs

Filesystem

Tool	Description
`read_text_file`	Read source files (offset + limit)
`write_file`	Create or overwrite files
`edit_file`	Find-and-replace edits
`multi_edit`	Multiple edits in one file
`replace_regex`	Regex replace in file
`apply_patch`	Unified / Codex-style patches
`glob`	Find files by pattern (sorted by mtime)
`grep`	Search content (content / files / count modes)
`list_directory`	List folder contents
`directory_tree`	Recursive tree as JSON
`create_directory`	Create folders
`delete_file` / `delete_directory`	Remove files or dirs
`copy_file` / `move_file`	Copy or rename
`read_file_base64` / `write_file_base64`	Binary file support

Shell

Tool	Description
`run_command`	Run shell commands (`npm test`, builds, …)
`shell_status` / `shell_reset`	Persistent shell session
`start_process`	Long-running / background commands
`process_status` / `process_output` / `stop_process`	Manage background jobs

Git

Tool	Description
`git_status` / `git_diff` / `git_log`	Inspect repo
`git_add` / `git_commit`	Stage and commit
`git_branch` / `git_checkout`	Branch list, create, switch (local only)
`git_restore`	Restore tracked files to last commit
`git_push` / `git_pull`	Sync with configured remote
`git_stash` / `git_reset`	Stash and reset

Claude Code ↔ MCP mapping

Claude Code	This server
`Read`	`read_text_file`
`Write`	`write_file`
`Edit` / `MultiEdit`	`edit_file` / `multi_edit`
`Glob` / `Grep` / `LS`	`glob` / `grep` / `list_directory`
`Bash`	`run_command`
—	`apply_patch`, `git_*`, `project_context`

⚙️ Configuration

Copy .env.example → .env:

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

# OpenAI Secure Tunnel (optional)
OPENAI_TUNNEL_ID=
OPENAI_TUNNEL_API_KEY=

Variable	Default	Description
`WORKSPACE_PATH`	`cwd`	Your project root (like `cd` before `claude`). Auto-loads `CLAUDE.md` / `AGENTS.md` into MCP instructions
`CHATGPT_AUTO_APPROVE`	`true`	Tool annotations to reduce ChatGPT popups
`MCP_SESSION_RECOVERY`	`true`	Auto-recover stale sessions after restart
`SHELL_TIMEOUT`	`120`	Max seconds for `run_command`
`FULL_DISK_ACCESS`	`true`	Access any path on the machine

Full machine access is enabled by default. WORKSPACE_PATH only sets the default cwd — absolute paths like D:\Projects\… work everywhere.

🏗️ 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

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

This server grants full access to your machine — files, shell, git. Only expose it through a tunnel you control. Never share your connector URL or tunnel API keys.

.env and secrets are gitignored
Audit log: .mcp-audit.log (optional, configurable)
Use on a trusted network / personal machine only

🩺 Troubleshooting

Problem	Fix
"Error in message stream" / "Lỗi trong luồng tin nhắn" right after "Looking for tools" — no server log	You did not tag the connector. New chat → + → More → enable connector, or type `@Local Coder` in the message. Then retry.
Resource not found on tool call	Refresh connector + new chat. Server auto-recovers sessions — ensure latest build is running.
Connection failed	Check `.\start.ps1` + tunnel are both running. URL must be HTTPS.
Permission popup every call	Settings → Apps → set connector to Ask before important changes. Don't use popup "Always allow".
Tool blocked by OpenAI safety	Not a server bug. Retry with `run_command` (response may include `run_command_fallback`). Affects `git_push`, `git_checkout`, `delete_directory` occasionally.
`stream canceled` in tunnel log	Server/tunnel restarted mid-session → refresh connector, new chat.
Tunnel URL keeps changing	Switch to OpenAI Secure Tunnel (`openai-tunnel.bat`).
Access denied	Wrong path or OS permissions on that file.
git not found	Install Git.

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

📚 References

📄 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

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
profiles		profiles
public/ui		public/ui
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
openai-tunnel-init.bat		openai-tunnel-init.bat
openai-tunnel-stop.bat		openai-tunnel-stop.bat
openai-tunnel.bat		openai-tunnel.bat
openai-tunnel.ps1		openai-tunnel.ps1
package-lock.json		package-lock.json
package.json		package.json
start.bat		start.bat
start.ps1		start.ps1
stop.bat		stop.bat
stop.ps1		stop.ps1
tsconfig.json		tsconfig.json
tunnel.bat		tunnel.bat
tunnel.ps1		tunnel.ps1

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ChatGPT Local Coder

✨ Why this project

🚀 Quick Start

🔌 Connect ChatGPT

1. Enable Developer Mode

2. Expose your server (pick one tunnel)

3. Create a connector

4. Use in chat — must tag the connector

🌐 Tunnel options

Option A — OpenAI Secure MCP Tunnel (recommended)

Option B — Cloudflare Quick Tunnel

🧰 Tools

Onboarding (call these first)

Filesystem

Shell

Git

Claude Code ↔ MCP mapping

⚙️ Configuration

🏗️ Architecture

🧪 Development

🔒 Security

🩺 Troubleshooting

📚 References

📄 License

⭐ Support

🇻🇳 Tiếng Việt

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

ChatGPT Local Coder

✨ Why this project

🚀 Quick Start

🔌 Connect ChatGPT

1. Enable Developer Mode

2. Expose your server (pick one tunnel)

3. Create a connector

4. Use in chat — must tag the connector

🌐 Tunnel options

Option A — OpenAI Secure MCP Tunnel (recommended)

Option B — Cloudflare Quick Tunnel

🧰 Tools

Onboarding (call these first)

Filesystem

Shell

Git

Claude Code ↔ MCP mapping

⚙️ Configuration

🏗️ Architecture

🧪 Development

🔒 Security

🩺 Troubleshooting

📚 References

📄 License

⭐ Support

🇻🇳 Tiếng Việt

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages