gpt-worker Manual

Step 1: Clone the Repository & Link the Command

1. Clone the repository into any working directory:

   git clone https://github.com/Nihondo/gpt-worker.git
   cd gpt-worker

2. Create a symlink in a directory that is in your PATH (such as Homebrew's bin):

   ln -s "$(pwd)/bin/gpt-worker" "$(brew --prefix)/bin/gpt-worker"

Step 2: Register the Skill for Your Agent (SKILL.md)

Link SKILL.md into your coding agent's skills directory so the agent can discover and operate gpt-worker:

mkdir -p ~/.claude/skills/gpt-worker
ln -s "$(pwd)/SKILL.md" ~/.claude/skills/gpt-worker/SKILL.md

mkdir -p ~/.codex/skills/gpt-worker
ln -s "$(pwd)/SKILL.md" ~/.codex/skills/gpt-worker/SKILL.md

mkdir -p ~/.agents/skills/gpt-worker
ln -s "$(pwd)/SKILL.md" ~/.agents/skills/gpt-worker/SKILL.md

Step 3: Initialize & Deploy the Worker

Run init targeting your first project directory:

gpt-worker init -w /path/to/your-project

• On the first run, a browser window opens for Cloudflare login.
• Once authenticated, the Cloudflare Worker deploys automatically.
• Note the Server URL printed in the terminal (you can check it anytime with gpt-worker url).

Step 4: Configure ChatGPT

1. Enable Developer Mode:

2. Add MCP Connector:

3. Create a ChatGPT Project:

4. Set Project Instructions:

     Use the gpt-worker connector. It supplies its own operating instructions — follow them for every round.

Step 5: Register the Project URL & Enable Chrome Auto-Submit

1. Save your ChatGPT Project URL (from the browser address bar https://chatgpt.com/g/...) into the CLI:

   gpt-worker chat-url "https://chatgpt.com/g/g-p-.../project"

When configured, Chrome will prepare and, when Apple Events is enabled, submit task prompts automatically.

2. Allow Chrome Background Submission (One-Time Setup):

To enable background prompt typing and submission without stealing window focus, enable Apple Events scripting in Chrome:

[You / Local Agent]                             [ChatGPT]
        │                                           │
        │── 1. gpt-worker task "<goal>" ───────────>│
        │                                           │ (Inspects repo & drafts plan)
        │<── 2. gpt-worker wait (Receive PLAN) ─────│
        │                                           │
   (Edit code & run tests locally)                  │
        │                                           │
        │── 3. gpt-worker report ──────────────────>│
        │                                           │ (Reviews diff & verifies tests)
        │<── 4. gpt-worker wait (DONE or next step) │

1. Start the Bridge Process

Before starting work, ensure the local bridge process is running for your workspace:

gpt-worker start -w .
gpt-worker status -w .

2. Queue a Task (`task`)

Describe your goal in natural language:

gpt-worker task "Fix the validation error styling on the login page" -w .

Chrome opens your ChatGPT Project, and the task prompt is automatically entered and submitted (requires the Chrome "Allow JavaScript from Apple Events" setting described above).

3. Wait for the Plan (`wait`)

ChatGPT inspects workspace files and prepares a plan:

gpt-worker wait -w .

When received, the plan is printed in the terminal. Review it to ensure it is sound and safe.

4. Execute Changes & Run Tests

Your local agent (Claude Code, Antigravity, etc.) or you modify the code and run your test suite locally.

5. Report Results (`report`)

Report modified file counts and test results back to ChatGPT:

gpt-worker report --changed 2 --tests "All 8 tests passing" -w .

6. Receive Review Results (`wait`)

Run wait again to receive ChatGPT's evaluation:

gpt-worker wait -w .

If ChatGPT determines the goal is achieved (DONE), you are finished! If there are follow-up instructions, repeat from step 4.

7. Stop the Bridge Process

When finished, stop the local bridge process:

gpt-worker stop -w .

Starting a New Chat & Managing Conversation Threads

gpt-worker remembers the ChatGPT conversation thread (URL) for each workspace so it can seamlessly continue the discussion in the same thread. If a conversation becomes too long and sluggish, if you want a clean slate for a new feature, or if you want to switch to a conversation you opened manually in your browser, use the following commands:

gpt-worker chat new -w .

gpt-worker chat attach "https://chatgpt.com/g/g-p-.../c/..." -w .

gpt-worker chat status -w .

Adding Another Project

No need to redeploy the Worker or reconfigure ChatGPT. Simply run init in the new directory:

gpt-worker init -w /path/to/another-project

Setting Project-Specific Guidelines (`guidance`)

Set standing rules for ChatGPT (e.g., "Always use Vitest", "Enforce strict TypeScript"):

gpt-worker guidance "Always write tests in Vitest. Prefer functional components." -w .

gpt-worker guidance -w .

gpt-worker guidance --clear -w .

Managing Read Permissions (allow-read and deny-read)

By default, files listed in .gitignore cannot be read by ChatGPT, while normal tracked files can be read. You can configure granular read policies using allow-read and deny-read:

• Policy priority: Sensitive files (.env, private keys, etc.) > deny-read > .gitignore baseline (with allow-read exceptions). Sensitive paths can never be read.
• allow-read <path>: Explicitly allows direct MCP read_file calls for a Git-ignored file or directory. Directory contents remain hidden from listing and search.
• unallow-read <path>: Removes an allow-read exception.
• deny-read <path>: Explicitly denies reads for any file or directory (whether tracked or previously allowed). Denied paths are completely hidden from listing, search, and direct reads.
• undeny-read <path>: Removes an explicit deny rule. If the path was also allowed, the underlying allow-read exception becomes active again.

gpt-worker allow-read config/test-fixture.json -w .
gpt-worker allow-read fixtures -w .

gpt-worker allow-list -w .

gpt-worker unallow-read config/test-fixture.json -w .
gpt-worker unallow-read fixtures -w .

gpt-worker deny-read secret-docs -w .
gpt-worker deny-read config/internal.json -w .

gpt-worker deny-list -w .

gpt-worker undeny-read secret-docs -w .
gpt-worker undeny-read config/internal.json -w .

*Note*: gpt-worker status displays both read allowed and read denied paths. Sensitive files (.env, .ssh/, private keys) cannot be unblocked by either list.

Giving ChatGPT the Whole Project at Once (`workspace_bundle`)

Instead of reading files one by one, ChatGPT can call workspace_bundle to receive the project's readable text files as a single .tgz archive, which it opens in its own sandbox and reads selectively. This saves many round trips on a task that needs broad context. You do not run it yourself; ChatGPT calls it when it needs it.

• Same rules as every other read: only what ChatGPT could already read is included. Sensitive files (.env, private keys, …), Git-ignored files, paths you deny-read, and noisy folders (node_modules, build output) are left out and are not named or counted. A path you allow-read stays direct-read only and is not put in the archive.
• Secrets are masked before packing: every secret the scanner finds is replaced with [REDACTED:<rule>], and local paths are normalized to [workspace]/[home]. If a secret cannot be masked in place, that file is left out instead.
• What is not included: binary files, symbolic links and files over 1 MiB. BUNDLE.md, the first file in the archive, lists them and says whether the archive is complete.
• Size: 1 MiB by default, at most 4 MiB. If the project is too large ChatGPT gets an error with a per-folder breakdown and asks for a narrower path; nothing is cut off silently.
• ChatGPT asks you to approve opening the archive. The first time, ChatGPT shows a dialog ("Materialize the file?" / 「ファイルを実体化しますか？」). Choose Allow for this conversation (from the arrow beside Allow) so it does not ask again in that conversation; choosing plain Allow asks each time. A new conversation asks again.
  • If you decline, ChatGPT is told you declined and will not retry the archive; ask it to read files one by one instead.
  • If nobody answers, ChatGPT waits indefinitely (observed for over 15 minutes). gpt-worker cannot see the dialog, but it can see that ChatGPT was handed an archive and then went quiet: gpt-worker wait prints a notice when that happens and a reminder if the silence lasts, and gpt-worker status shows a hint line. It cannot tell an unanswered dialog from ChatGPT still reading the archive, so treat it as a prompt to look at the ChatGPT window, not as proof.
• Requires tar (present on macOS and Linux by default).

Inspecting Configuration

Inspect configured Project URLs and auto-submit preferences:

gpt-worker show-config -w .

Listing Registered Workspaces

List all workspaces registered on this machine and their bridge statuses:

gpt-worker workspaces

Web Dashboard

Your Cloudflare Worker also serves a browser dashboard — a kanban-style view of the queue and task history, plus the ability to ack/discard messages, edit guidance/limits, and queue a new task from the browser instead of the CLI. There are two login paths, at two different URLs:

One workspace at a time, with that workspace's own owner token:

gpt-worker url -w .

Open the WebUI URL (https://<your-worker>.workers.dev/dashboard/<workspace_id>) and log in with that same owner token (the gpt_token shown above for that workspace — not the shared hub token; that one is rejected here). Login exchanges the token for a 24-hour browser session (an HttpOnly/Secure cookie scoped to that workspace's own dashboard path) — the owner token itself is never sent again after that.

Every registered workspace at once, with the shared hub token:

gpt-worker url

Open the WebUI URL (https://<your-worker>.workers.dev/dashboard/hub) and log in with that shared hub token (not a single workspace's gpt_token; that one is rejected here). After login you get a workspace picker listing every workspace registered with this shared connector (the same set gpt-worker init adds you to and list_workspaces shows ChatGPT); selecting one gives you the exact same view/actions as that workspace's own dashboard above. The two logins are entirely separate sessions — a workspace session can't reach the hub dashboard and a hub session can't directly authenticate a workspace's own dashboard URL — and the hub only ever reaches a workspace_id it has registered, never an arbitrary one.

Capabilities and behavior:

• Can do: browse pending messages and full task exchange history with timestamps, ack or discard messages, view and edit guidance or body limits, view/edit/clear browser settings (shared ChatGPT Project URL, workspace override, conversation URL), start new tasks from the browser (available from both the per-workspace and hub dashboards).
• MCP Access history: the MCP Access tab (next to Tasks and Messages) shows what ChatGPT did through the MCP connector — see MCP Access history below.
• Real-time updates: supports real-time push updates over WebSocket, immediately reflecting task progress, message exchanges, and setting changes in the browser (automatically falls back to adaptive polling — ~30s while active, ~2m when idle, ~60s for the Hub workspace list — if the WebSocket disconnects, and pauses updates while the tab is hidden).
• Data retention: follows standard Worker policies (an acked message is removed after 7 days, and completed task history after 30 days). MCP access history is kept for 24 hours, at most 1000 calls per workspace.

A workspace's own dashboard session is revoked immediately if you rotate that workspace's owner token (gpt-worker rotate --gpt -w .) or remove the workspace (gpt-worker remove -w . --yes). A hub dashboard session is revoked immediately if you rotate the shared hub token (gpt-worker rotate --hub) — see Data Retention.

#### MCP Access history

The MCP Access tab lists every tool call ChatGPT made through the connector, newest first, so you can see what it read (or tried to read) and why something was refused. Each row shows:

• What: a plain-language tool name (Read file, Git diff, Search, Batch, …) with the raw tool name beneath it.
• Target: the file or directory path, or a fixed description such as "workspace search" or "PLAN · iteration 2".
• Result, as a text badge (never color alone): OK, Gate (blocked: no active task, or the read window closed — see *Time-Bounded Access*), Deny (denied: a sensitive, Git-ignored, or out-of-workspace file), NG (an error), or Mix (a batch with different outcomes; open it to see each call). The badge is kept short to fit; the detail pane spells the result out ("Blocked", "Denied").
• Time taken and the task it belonged to.

To keep the list readable, consecutive successful file reads of the same task (within 30 seconds of each other) fold into one "Read file × N" row. Denials, blocks, and errors are never folded. Untick Group repeated reads to see every call. The Tool and Result filters apply to the whole history, not just the loaded page — use Load more to go further back. The tab works the same in the per-workspace and hub dashboards.

What is recorded — and what never is: only metadata (time, tool, connector, task ID, a safe target, result class, a short reason code, duration). File contents, diffs, search queries or hits, message bodies and titles, error text, raw tool arguments/results, secrets, and absolute paths are never stored. Paths that would point outside the workspace are shown as a fixed label instead. This is an audit trail of *access*, not a copy of what was accessed.

The default timeout for wait is 15 minutes. If a timeout occurs, you can resume waiting without re-submitting the task:

gpt-worker state -w .

gpt-worker wait -w .

Handing a Task to Another Agent

When the agent you are working with has to stop mid-task — a rate limit is close, or the session is ending — it can hand the task to a different agent instead of finishing the round normally:

gpt-worker handoff --changed 3 --tests "unit tests pass; integration not run" --reason "rate limit" -w .

The agent then stops, without waiting. ChatGPT writes a handoff brief carrying the task's history — the goal, what is done, the decisions and the approaches already ruled out — and queues it. A different agent picks it up later with the ordinary wait command:

gpt-worker wait -w .

The brief stays in the queue for 7 days, so the second agent can start whenever you like — a different model, a different session, or the same machine tomorrow. Nothing needs to be copied between the two agents: the Worker retains the task state, allowing the resuming agent to take over without any direct handoff from the previous session.

What carries over is the context ChatGPT itself accumulated while planning and reviewing. Because ChatGPT stays on the task while the local agents change, the review after the handoff still accounts for the work done before it.

If the previous agent never got to run handoff — it was abruptly cut off without stopping cleanly — a new agent can run handoff itself to claim the task. The handoff command works in either direction, and neither ChatGPT nor the Worker needs to distinguish which agent called it:

gpt-worker handoff --reason "previous agent stopped without reporting; taking over" -w .

Skip --changed/--tests (or say plainly that nothing is verified) rather than guessing at work you did not do — ChatGPT re-checks the repository itself (git_status/git_diff) before trusting any report anyway. This only works while the task is still mid-round; if it fails, a reply may already be queued — run gpt-worker wait instead. Otherwise, follow it with gpt-worker wait to receive the brief.

If a handoff brief doesn't fit in the message size limit (16 KB by default), raise it for that workspace:

gpt-worker limits 65536   # bytes; run with no argument to see the current value
gpt-worker limits --reset # back to the default

Every message — from either side — lands in the same long-lived ChatGPT conversation this workspace reuses across tasks, so raise this deliberately: a larger cap means faster growth toward that conversation's context limit, not a free allowance.

Updating & Redeploying

When you update gpt-worker via git pull, redeploy the Cloudflare Worker if the update includes changes to the Worker code (worker/):

cd /path/to/gpt-worker
git pull

npm run deploy

gpt-worker stop -w /path/to/your-project
gpt-worker start -w /path/to/your-project

Deregistering a Workspace

To remove a project and purge its records from the local machine and remote Worker:

gpt-worker remove -w /path/to/project --yes

Chrome Auto-Submit Not Working

To allow background script execution in an existing tab:

1. In Chrome, open View → Developer → check Allow JavaScript from Apple Events.
2. Relaunch Chrome completely.
3. Any existing text or draft in the input box (including connector mentions) is cleared and overwritten with the new prompt to prioritize uninterrupted background execution.

Safety Guarantees

• Plan Review: Always verify the plan generated by ChatGPT before execution. Check for unwanted file deletions or unexpected external commands.
• Secret Blocking: .env, private keys, .ssh, and .aws are always blocked from ChatGPT read requests.
• Time-Bounded Access: ChatGPT can only inspect workspace files while an active task is running.

Data Retention

Your Cloudflare Worker (deployed to your own account in Step 3) retains task traffic for a limited period, which means some temporary data is stored remotely compared to a purely local setup:

• Task message bodies (goal text, plans, execution reports) are automatically deleted from the Worker 7 days after being delivered and acknowledged.
• Task history (goal text and outcome summary, used to give ChatGPT context on past tasks) is automatically deleted from the Worker 30 days after the task reaches a final outcome (done or blocked). An in-progress task is never deleted while it's active.
• MCP access history (metadata only — see MCP Access history) is deleted 24 hours after each call, and only the newest 1000 calls per workspace are kept. It is removed with the workspace by gpt-worker remove.
• Web dashboard sessions expire after 24 hours and are then swept automatically; a workspace's own dashboard session is also revoked immediately by rotating that workspace's owner token or removing the workspace, and the shared hub dashboard's session is revoked immediately by rotating the shared hub token.
• To permanently wipe all task/queue records for a workspace from your Cloudflare account, run gpt-worker remove -w <dir> --yes (see Deregistering a Workspace). There is no way to delete a single past task's history short of removing the whole workspace.

Exit codes

Code	Meaning
0	Success
1	Error (the message says what to do)
2	wait timed out with no reply yet — run it again. If ChatGPT was handed a workspace_bundle archive and has been silent since, the message says so (it may be waiting for your approval in the ChatGPT window)
3	wait delivered a reply, but the task did not advance. The reply is printed; inspect with gpt-worker state, and if the task is truly stuck, gpt-worker discard-task --yes
4	The Worker could not be reached. For task/report/handoff the message says whether the request may still have been applied — check gpt-worker state before repeating it. wait can also exit 4 right after printing a reply whose acknowledgement could not be confirmed: follow the guidance it prints (check gpt-worker state and gpt-worker queue --task <task id>) rather than assuming a redelivery

Commands retry transient network failures on their own (a few short attempts). wait goes further and keeps trying until its own timeout, so a brief outage during a long wait does not end it.