Codex ACP for Copilot
Use your existing ChatGPT plan in GitHub Copilot Chat. Sign in once with your ChatGPT account and get Codex in the model picker with everything Copilot offers: agent mode, tools, approvals, diffs, skills, custom agents and instruction files. Prefer pay-as-you-go? You can optionally use an OpenAI API key instead.
- Your plan, no extra subscription. Sign in with your ChatGPT account in the browser. Usage counts against your plan's limits.
- Full Copilot experience. Copilot keeps the agent loop and tools; Codex is the model driving them.
- API keys are optional. Save an OpenAI API key if you would rather pay per token.
- Live usage in the status bar. See your 5-hour and weekly Codex plan usage at a glance, so you know how much of your plan is left without leaving the editor.
- Prompt cache hit ratio in the status bar. Watch how much of a chat's prompt Codex serves from its own cache, updated after every turn, to see that your sessions are staying fast and cheap.
- Built for daily use. Thinking Effort levels, streaming, cancellation, image attachments and token usage.
Under the hood, the extension runs the Codex ACP adapter (@agentclientprotocol/codex-acp) as a local process. It is a port of claude-acp-for-copilot.
Unofficial. Not affiliated with OpenAI or GitHub. "Codex", "ChatGPT" and "GitHub Copilot" are trademarks of their owners.
Your account. Use your own credentials. OpenAI's terms for your account type decide which credentials may be used with which tools. Browser sign-ins stay in the adapter, which keeps the tokens; the extension never sees them, reads no token file and makes no OpenAI API requests itself.
Requirements
- VS Code 1.105 or newer with GitHub Copilot Chat, in a trusted workspace (not Restricted Mode or a virtual workspace).
- A ChatGPT plan or an OpenAI API key. Codex decides what each credential may reach; the extension only passes the credentials on.
- npm and network access to the npm registry, for the first install and whenever a new adapter version ships. Nothing is installed globally and no package script of the adapter runs.
Getting started
- Run Codex ACP: Set Up, or accept the prompt after installing. It installs the pinned adapter into global storage and starts it.
- Run Codex ACP: Sign In (ChatGPT or API Key) if you are not signed in yet: a ChatGPT account in the browser, or an OpenAI API key.
- In Copilot Chat, pick a model under Codex Agent. The Thinking Effort control beside the model sets how much reasoning Codex spends before it answers.
Logs go to the Codex ACP output channel. At the default Info level each request is named with its model, the message count and the tools sent with it, and a chat session is logged when it is created, reused or replaced. Set the level to Debug to also see the request shape, tool titles and permission requests.
Signing in
| Method |
Billing |
| ChatGPT account (browser sign-in run by the adapter) |
Your ChatGPT plan, with 5-hour and weekly limits |
| OpenAI API key (saved in the OS keychain, never in settings or logs) |
Per token, against the key's account |
codexAcp.authPreference decides what is used when both exist. The default, auto, lets a saved key beat a signed-in account; chatgpt keeps the account and withholds CODEX_API_KEY and OPENAI_API_KEY from the agent.- Saving or removing a key restarts the agent so it picks the change up, except with
codexAcp.authPreference set to chatgpt: the agent ignores the key either way, and the message you get after saving says so. Choosing a browser sign-in while a key is saved asks whether to remove the key first.
- The agent runs in a Codex home of its own (
codex-home in the extension's global storage), so a ChatGPT sign-in here is separate from the one the Codex app or CLI uses, and their config, MCP servers and plugins do not apply to it. Chats Codex saved under ~/.codex cannot be resumed; the extension rebuilds them from the chat transcript.
- An account billed per token has no ChatGPT plan limits, so the usage item shows only the cache share.
- Browser sign-in only in this release: there is no device-code flow yet.
Commands
| Command |
What it does |
Codex ACP: Set Up |
Installs the adapter if needed, starts the agent, refreshes models |
Codex ACP: Sign In (ChatGPT or API Key) |
Runs the chosen sign-in method |
Codex ACP: Set OpenAI API Key |
Saves a key and restarts the agent |
Codex ACP: Choose Which Credentials to Use |
Picks between the saved key, the ChatGPT account, or automatic |
Codex ACP: Remove OpenAI API Key |
Deletes the saved key; the signed-in account is used instead |
Codex ACP: Restart Agent |
Restarts the agent, dropping cached models and sessions |
Codex ACP: Show Account |
Shows which credentials are in use |
Codex ACP: Refresh Usage |
Re-reads the plan limits in the status bar |
Settings
| Setting |
Default |
Meaning |
codexAcp.permissionMode |
auto |
auto approves the permission requests the agent makes. ask shows the options it offers; no answer within five minutes declines. Copilot's own confirmations apply to its tools either way. Machine-scoped. |
codexAcp.authPreference |
auto |
auto uses the saved key when there is one, otherwise the account; apiKey uses the key; chatgpt ignores the key and withholds it from the agent. Restarts the agent. Machine-scoped. |
codexAcp.sessions.idleTimeoutSeconds |
120 |
A chat that has been idle this long gives back its agent session; its next message resumes the stored conversation. 0 keeps the session until the chat limit or a restart closes it. Machine-scoped. |
codexAcp.agent.idleShutdownMinutes |
30 |
When no chat has a session left, the agent process is stopped after this many minutes, which also frees the helper processes it started per session, and started again by the next message. 0 keeps it running for as long as the window is open. Machine-scoped. |
codexAcp.usage.showInStatusBar |
true |
Shows the cache share of the most recently used chat, updated after every turn, and for plan accounts the 5-hour and weekly plan usage (warning at 80%, erroring at 95%). Plan usage is read without a model call, only when you click the item or run Codex ACP: Refresh Usage; it is never read automatically. |
codexAcp.debug.dumpRequests |
false |
Writes every request Copilot sends, in full, as a JSON file in the extension's global storage (request-dumps, newest 40 kept). The files hold your prompts and workspace context, so leave it off unless you are working out what Copilot sends. Machine-scoped. |
How it works
- The pinned adapter is installed in global storage with
npm ci --ignore-scripts. A failed update leaves the previous version available.
- Each chat has its own agent session. Idle sessions are released and resumed on the next message; a change to the chat's tools or guidance starts a new session with its history.
- Copilot's tools reach Codex through a loopback-only MCP bridge. Tool calls go through Copilot's confirmations, and Codex's own editing and command tools are disabled. Additional MCP servers configured through
CODEX_CONFIG can still expose their tools to the agent.
- Copilot's instructions, skills and custom agents reach the agent along with its system prompt; the extension removes Copilot's identity and personality and adds its own identity guidance.
- The status bar shows the latest chat's cache share and, for plan accounts, usage limits. Limits are read only when you click the item or run Codex ACP: Refresh Usage.
- Thinking Effort comes from the adapter's model catalogue. If the account's default model is absent from the catalogue, the extension warns that it cannot apply the selected effort.
Troubleshooting
- No models. Run Codex ACP: Set Up. If that does not help, check the Codex ACP output channel, then run Codex ACP: Restart Agent.
- Sign-in required. A warning says so with a Sign In button. After a browser sign-in, the agent restarts from the same notification, or run Codex ACP: Restart Agent.
- Sign-in failed. The notification
Codex ACP: sign-in failed: … gives the reason the adapter reported, for example an expired browser login or no network; the output channel has the same failure as Signing in with <method> failed: …. Run Codex ACP: Sign In (ChatGPT or API Key) again; Codex ACP: Show Account says which credentials the agent is using.
- npm could not be found. Install Node.js, which includes npm, then reload the window. npm's own output is in the Codex ACP output channel.
- The adapter install failed. The output channel shows the npm output and the exit code. Check the registry connection, then run Codex ACP: Set Up again. If an earlier version is installed, it keeps being used until the new one succeeds. To start from scratch, delete the
adapter folder in the extension's global storage and reload.
- The agent keeps stopping. Three starts that die within ten seconds make the extension refuse further starts for two minutes, with a message naming Codex ACP: Restart Agent. Check the output channel for the reason the process exited.
Privacy
- The extension stores almost no conversation text: the one write it makes by default is a chat's opening words, cut to 40 characters, used as its label in the cache figure it shares between windows. A saved session keeps only the agent's session id, the folder and hashes of the messages, tools and prompt, so a reloaded chat can find its conversation again. The adapter keeps its own transcript in its store and sends your prompts to OpenAI under your account.
- The adapter, its logs and a version marker live in the extension's global storage. An API key lives in secret storage and reaches only the local agent process.
- The extension makes no OpenAI API requests of its own and collects no telemetry; every model call goes through the adapter, on your credentials.
- Request dumps contain your prompts and workspace context, so they are off by default and only written when you turn
codexAcp.debug.dumpRequests on; the newest 40 are kept.
- Logs never record your email address or organization at the default level.
License
MIT. See LICENSE.
| |
