GPT Web Agent

中文说明

Give a browser-based AI assistant tools to work on a real local project: read code, edit files, run tests, inspect failures, and keep task checkpoints.

Status: experimental 0.2.0. Local MCP integration tests and a live ChatGPT web code-edit/test/fix workflow pass; see validation. Source: yyyqt/gpt-web-agent. Not published to npm or the ChatGPT plugin store.

ChatGPT web (reasoning and tool selection)
          │ MCP through a private authenticated tunnel
          ▼
GPT Web Agent (local tool runtime)
          ├─ workspace files + optimistic edits
          ├─ optional host commands + bounded results
          └─ task checkpoints + metadata-only audit log

No model inference API, reverse proxy for ChatGPT, browser session extraction, or scraping of ChatGPT conversations. The runtime itself needs no OpenAI API key. The optional official tunnel has its own runtime credential and permissions. This project does not promise unlimited tokens or bypass account limits.

Quick start

Requirements: Node.js 22+, macOS or Linux for shell execution. Use a disposable project directory for first use. Clone this repository or extract its source archive, then run:

npm ci --ignore-scripts
npm run check
mkdir -p /tmp/bridge-demo
node src/cli.js --root /tmp/bridge-demo

The default transport is MCP stdio: it waits for an MCP client, not terminal input. It exposes file tools and task checkpoints. Shell tools are absent by default. To enable command execution:

node src/cli.js --root /tmp/bridge-demo --allow-host-exec

--allow-host-exec gives the assistant unsandboxed host shell access. Commands run as the current OS user. cwd, blocked file names, and a reduced environment are not a sandbox: commands can access paths outside the workspace, use the network, and launch other processes. For stronger isolation, run the entire runtime in a dedicated unprivileged VM/container. Do not mount secrets or the Docker socket into that environment. No built-in container integration is claimed.

Connect through the ChatGPT setup guide. For any stdio MCP client, adapt the configuration example.

Optional loopback-only HTTP transport:

node src/cli.js --root /tmp/bridge-demo --transport http --port 8788

Endpoint: http://127.0.0.1:8788/mcp; health: /health. HTTP rejects browser Origins and unexpected Host headers. It has no public authentication server and must not be exposed through an unauthenticated public forwarding URL. Use an access-controlled private tunnel; all trusted local clients share this workspace.

Related MCP server: Coding Tools MCP

Tools

--read-only removes write/task-save/shell tools. Runtime metadata still writes to .web-agent/. File tools deny parent traversal, secret-like names, .git, symlinks and hard-linked files. Secret detection is deliberately incomplete.

Background tasks and Codex

Add --allow-codex to expose start_codex. Install the official Codex CLI and run codex login first. Prompts go through stdin to codex exec --ignore-user-config --sandbox workspace-write; no shell interpolation or bypass flag. The CLI uses its existing login and default model, not the global user's MCP/model/hook config. Project-level Codex policies can still apply. Codex consumes its own account quota.

node src/cli.js --root /absolute/project --allow-host-exec --allow-codex \
  --max-seconds 7200 --max-output-bytes 1048576 --max-file-bytes 4194304

Wait for a job ID before leaving. Already dispatched shell/Codex jobs run without an open browser while the runtime stays alive. Codex executes its own model/tool loop. Ordinary ChatGPT cloud-turn completion after tab closure depends on ChatGPT and pending approvals; this bridge does not guarantee it or start new ChatGPT turns. Keep the host awake and online. See background operation.

Completed results (including bounded output) survive restart in local private .web-agent/job-*.json files. Graceful server shutdown cancels active jobs. Unfinished records after a crash are reported as interrupted, never blindly rerun or killed using stale PIDs. This is result persistence, not reboot recovery.

Limits are configurable: --max-seconds (default 600, up to 86400), --max-concurrent (2, up to 16), --max-output-bytes (131072, up to 16777216), --max-file-bytes (1048576, up to 16777216). Both job types share concurrency. Keep two jobs unless parallel changes are isolated. Retention: 100 job results, 100 task checkpoints; search visits at most 2000 entries. Truncation is explicit. PTYs, daemonized child processes, scheduling, browser and SSH modules are not provided.

Verify the first real workflow

After connecting, use the demo prompt. Confirm that the assistant calls tools, observes a failing test, corrects the code, runs it again, and reports the real exit code. Verify the resulting files locally. A written plan or fabricated terminal transcript does not count as acceptance.

Development and contribution

npm ci --ignore-scripts
npm run check
npm audit --omit=dev
npm pack --dry-run

Tests cover real stdio/HTTP MCP round trips, a failing-test/fix/passing-test loop, read-only discovery, path rejection, edit conflicts, task persistence, bounded output, process cancellation, timeout, and local HTTP request validation.

See architecture, security, and contribution notes. MIT licensed. Independent project, not endorsed by OpenAI. No source code was copied from AgentDock or the article.