# Agent with ChatGPT

**Your ChatGPT subscription is sitting idle. Your coding agent's tokens are not.**

You already pay for ChatGPT Plus or Pro, and most of that web quota goes unused. Meanwhile your coding agent (Codex) burns scarce tokens on planning, reasoning and code review.

**Agent with ChatGPT moves that thinking to ChatGPT on the web. Codex only executes.**

- **One-paste setup.** Paste one short prompt into your agent. It installs and configures everything.
- **Built for Codex, works with Claude Code too.** The same install serves either agent.
- **No API key.** It uses your ChatGPT web subscription, within ChatGPT's normal usage limits.
- **One connection for all your projects.** No new connector per repository.
- **Independent review.** ChatGPT reads your workspace and the real Git diff through a read-only MCP connector, then checks the agent's work.
- **Easy updates.** The Skill checks for new versions on its own, and a short prompt updates it on demand.

[简体中文](README.zh-CN.md) · [Troubleshooting](docs/troubleshooting.md) · [Security](docs/security.md)

## Install: one paste

Paste this into **Codex** (or Claude Code). It works the same for both: the agent identifies itself in step 1.

You do not need to know Git, Node.js, MCP or OAuth. The agent does the technical work.

```text
Install "Agent with ChatGPT" on this machine. Do every step yourself, in order, and skip none.

1. Identify yourself. If you are Codex: AGENT=codex and AGENT_HOME = the CODEX_HOME environment variable if it is set and not empty, else ~/.codex. If you are Claude Code: AGENT=claude and AGENT_HOME = CLAUDE_CONFIG_DIR if set and not empty, else ~/.claude. "~" means my home directory.
2. Make sure git, Node.js 20 or newer, corepack ("corepack --version" must work) and cloudflared are installed. Install what is missing (macOS: brew; Windows: winget, the package for cloudflared is Cloudflare.cloudflared; Linux: the system package manager). Ask me only if administrator rights are required.
3. Clone https://github.com/FinalHope487/agent-with-chatgpt into ~/agent-with-chatgpt. If the folder already exists, first check that it is this repository and run "git status --short". If it is clean, run "git pull --ff-only". If it has local changes or is a different repository, stop and tell me why. Never overwrite or discard existing files.
4. Inside that folder run "corepack pnpm install" and then "corepack pnpm build". If either fails, stop and show me the error.
5. Copy the whole folder skill/agents-with-chatgpt/ to AGENT_HOME/skills/agents-with-chatgpt/ (replace the old copy if there is one). Then open the reference file for you: references/codex-with-chatgpt.md if you are Codex, references/claude-with-chatgpt.md if you are Claude Code (inside that copied folder). Replace the text <ACTUAL_CHECKOUT_PATH> in it with the absolute path of the cloned folder.
6. Read AGENT_HOME/skills/agents-with-chatgpt/SKILL.md, then the reference file from step 5, and carry out its "Workflow: first-time setup" exactly as written for my current project. Use the single shared hub connection. Never create a separate connector for this project.
7. Ask me only for things you cannot do yourself: logging in to ChatGPT or Cloudflare, a CAPTCHA, 2FA, a consent screen, or a choice the setup asks for. Give me one action at a time. Never say a browser step is done unless you checked it.
8. Once the setup works, if the file AGENT_HOME/agents-with-chatgpt-involvement.md does not exist, read references/involvement-setup.md in the installed Skill folder and run that short interview with me once. If the file exists, skip this step.
9. Finish with this checklist, each line PASS or FAIL: build OK, Skill installed, ChatGPT connected, file-read test. For the file-read test write down the workspaceId returned by "workspace add" and the workspaceId ChatGPT returned from workspace_info after reading a top-level file of my project; PASS only if they are identical. If any line is FAIL, say the install is not complete and why.
```

That's the whole install. Afterwards, tell your agent:

> Use Codex with ChatGPT to implement `<your task>`.

(For Claude Code: "Use Claude with ChatGPT to implement …". These phrases are what the installed Skill listens for.)

The first setup normally needs you to sign in to ChatGPT and approve the connector. Quick Tunnel needs no domain or Cloudflare account; a fixed domain is optional (see below).

## How it works

```text
You describe a task
        |
        v
ChatGPT (web)         plans, through a read-only MCP connector
        |
        v
Codex / Claude Code   edits files, runs commands and tests
        |
        v
ChatGPT (web)         independently checks the real Git diff
        |
        v
Done, or another focused fix
```

ChatGPT thinks and reviews. **The agent keeps full ownership of execution.** They exchange tiny structured messages, and ChatGPT pulls what it needs from your workspace by itself, so no file contents, diffs or logs are pasted into the chat.

This cuts the planning and review work your agent would otherwise do. It does not remove agent token use, and it does not guarantee a fixed saving.

## One setup, many projects

The default is **hub mode**: one local bridge, one public address and one ChatGPT connector for the whole machine. Each project is registered with the hub when you first use it:

```bash
c2c workspace add -w <project-path> --json
c2c doctor -w hub --json
```

`c2c` is this repo's CLI. Without a global command, run `node "<checkout>/bin/c2c.js" <command>`. Your agent does this for you.

**Connection choice.** A Cloudflare Quick Tunnel needs no domain, but its address changes when it restarts, and then the ChatGPT connector must be recreated. A domain whose DNS is on Cloudflare gives a fixed address and fewer repairs (`c2c prefs set --default-zone <domain>`, once). The fixed domain is optional.

## Updates

The installed Skill runs a cached update check about once a day, whenever you use it. If a newer version exists, the agent updates itself, then continues your task. It is not a background service: the check runs when the Skill is used.

To update right now, paste this:

```text
Update "Agent with ChatGPT". Follow these steps in order.

1. Identify yourself. Codex: AGENT_HOME is the CODEX_HOME environment variable if set and not empty, else ~/.codex, and your reference is references/codex-with-chatgpt.md. Claude Code: AGENT_HOME is CLAUDE_CONFIG_DIR if set and not empty, else ~/.claude, and your reference is references/claude-with-chatgpt.md.
2. Read AGENT_HOME/skills/agents-with-chatgpt/SKILL.md and your reference file in that folder. The line "checkout lives at:" in the reference gives the repo folder (the checkout). Do not clone another copy.
3. Run "git status --short" in the checkout. If it has local changes, preserve them. If you cannot safely preserve and restore them, stop and tell me.
4. Follow the reference's "Workflow: update" exactly. If you use "git stash", run "git stash pop" afterwards and check "git status --short" again before you claim success. Never reset or clean away my changes.
5. Run: node "<checkout>/bin/c2c.js" update-check --force --json. Tell me the version and report PASS or FAIL for the update. List any step that did not finish.
```

If something misbehaves, update first, then see [Troubleshooting](docs/troubleshooting.md).

## Tell your agent when to use ChatGPT (optional)

By default your agent decides, task by task, when to call ChatGPT, whether to open a new ChatGPT chat, and what result to ask for. ChatGPT acts as a read-only reviewer, and the agent makes every edit.

The install asks you these questions once. You can also say **"Set up ChatGPT involvement"** at any time to redo them. If the file is still missing, the Skill asks once the first time it is used. Your agent asks a few questions with its built-in question tool (which situations should go to ChatGPT, which should not, what extra context to give it first, what form of answer you want back) and saves a short advice file, `agents-with-chatgpt-involvement.md`, in the agent's home folder. It is advice only: it never overrides the Skill's rules, a missing answer means "use your judgment", and deleting the file restores the default.

## Security and limits

- **Read-only.** ChatGPT can read allowed workspace content. The server exposes no file-editing or shell tools.
- **Your agent executes.** Edits, commands, tests and commits happen locally.
- **Authorized.** The public connection needs OAuth and a one-time pairing code. Tokens are stored only as hashes.
- **Allowlist.** Only registered projects are reachable. Common secret files are blocked, and `.c2cignore` adds exclusions.
- **Shared boundary.** One hub connection can read **all** registered projects. Do not register repositories you do not want reachable through it.
- **You still sign in.** ChatGPT login, Cloudflare login (only for a fixed domain), CAPTCHA or 2FA are done by you. You need a ChatGPT plan that supports custom MCP connectors, and its usage limits still apply.

Details: [Security](docs/security.md) · [Architecture](docs/architecture.md) · [Protocol](docs/protocol.md) · [Roadmap](docs/roadmap.md)

## For developers

Needs Node.js 20+, Git, Corepack (pnpm) and, for the public connection, cloudflared.

```bash
corepack pnpm install
corepack pnpm build
corepack pnpm test
corepack pnpm typecheck
```

Unofficial community project. Not affiliated with or endorsed by OpenAI or Anthropic.

## Credits

Derived from [XiaoDuoYa/codex-with-chatgpt](https://github.com/XiaoDuoYa/codex-with-chatgpt) and its multi-project Hub edition by [FinalHope487](https://github.com/FinalHope487/codex-with-chatgpt). [MIT](LICENSE).