- Install and open CoS. Choose the download for your operating system and CPU.
- Choose what ChatGPT may access. In Settings → Workspace, approve a project folder and review the tool permissions.
- Connect the local tools. Configure a tunnel in Settings → Setup, press Connect, then add the Core app in ChatGPT's Developer mode.
- Load the companion extension. Press Open extension folder. In
chrome://extensions, enable Developer mode, choose Load unpacked and select that folder. Pairing is automatic. - Start a task. Choose a project and model in CoS, write your request and send it.
Want screen and keyboard control? Enable Desktop permissions and connect its separate app. On macOS, also grant Screen Recording and Accessibility in System Settings.
After an update: reload the companion extension and refresh the CoS apps in ChatGPT when prompted. These are two separate steps.
- Create a tunnel in Platform → Tunnels, in the same workspace you use in ChatGPT.
- Create a Restricted API key with Tunnels: Read and Tunnels: Use.
- Enter the tunnel ID and key in CoS and press Connect.
- In ChatGPT, enable Developer mode under Settings → Apps → Advanced settings, then create a custom app of type Tunnel. Review and enable its actions.
Core, Desktop and Plugins are separate connectors. Configure each surface you enable. Release packages include the pinned, checksum-verified tunnel-client.
Cloudflare quick tunnel: connect in CoS and use the displayed public URL as the MCP server URL in ChatGPT. The random path is a secret and changes on restart.
Your own HTTPS tunnel: forward to the loopback URL shown by CoS and preserve its secret path. Treat the resulting URL like a password.
| Connector | What it adds |
|---|---|
| Core | Local files, patches, terminals, generated-file downloads, session history, plans and workers. Available on all supported platforms. |
| Desktop | Screen inspection, mouse, keyboard and clipboard. Windows and macOS; macOS requires explicit enablement and OS permissions. |
| Plugins | External MCP tools such as Blender, Playwright and Memory, plus custom local or remote servers. Plugin guide. |
You choose the approved folders and capabilities. File tools enforce those roots; shell commands run with your normal user privileges. Desktop access applies to the desktop, and external plugins have their own permissions. Read-only mode disables writes, command execution and desktop control.
History is stored locally, with recording on and 30-day retention by default. Credentials use the operating system's secure storage. Review permissions before connecting: fresh installs enable Core capabilities and two workers; Windows also starts with Desktop permissions enabled.
Security policy · Tool reference · Architecture
Open + → Skills to import a .md or .txt instruction file, browse installed skills or open their folder. Type / in the composer to autocomplete a skill command. Skills start empty and use existing Core file tools; they do not install additional tools. See the skills guide for the file format and model-assisted installation.
Opening a chat in a project includes its exact virtual folder in the model's main instructions, even without an AGENTS.md file. It is the default working folder; the model can work elsewhere when your task needs it and existing permissions allow it. Selected skills remain complete ahead of optional AGENTS.md content.
Session history belongs to the local session, not a particular ChatGPT tab. The companion records messages and the actual local tool results so the app and the model can read earlier work.
Compact & Resume asks for a handoff, starts a fresh provider conversation and rebinds that same session. Task and worker history move with it. Automatic compaction uses configured local estimates and eligible live work; Pro models never auto-compact.
Workers keep their conversation when they finish. Send a follow-up to reuse one. The default is two simultaneous workers per family, configurable up to eight. Idle owned tabs can be reused or closed after fresh checks; the durable worker history remains. Drafts, active work and pins are protected.
Goal can decide the task is complete and send nothing. Loop continues within the brief until disabled. Both support ChatGPT helpers or an optional API backend.
Astra's finish boundary can receive queued instructions, plan checkpoints and automatic follow-ups through tools within the same working turn when Session finish is enabled. You can end the turn from the composer. This does not remove provider usage or context limits.
- Connected tunnel, empty Core Actions: open the Core plugin's Actions list in ChatGPT and check for
read(andexec_commandwhen local command access is enabled). Check the saved Core Tunnel ID and matching ChatGPT workspace, then refresh that plugin's actions. If the list remains empty, reconnect the affected tunnel in CoS when no task is running, refresh the plugin again, and use Home → Run checks. Each of Core, Desktop and Plugins uses its own tunnel ID. Extension pairing, tunnel health, a received HTTP request, and a nonempty tools/list response are separate checks. - Missing or stale tools: refresh the relevant CoS app in ChatGPT. Reloading the Chrome extension is a separate action. Workspace-published apps can retain a reviewed tool snapshot until an administrator updates it; see OpenAI's MCP app guidance.
- Tunnel rejects the API key or tunnel ID: check the saved tunnel ID, the selected setup profile, and that its key has Tunnels Read + Use for that tunnel. Extension pairing does not authenticate the tunnel. If Platform offers no matching ChatGPT workspace, retain the exact error for an access investigation; a different tunnel does not establish account eligibility.
- ChatGPT blocks a tool for safety: local permission alone does not prove that ChatGPT accepted or dispatched the call. Inspect the local tool history for the exact request. If no result exists, execution is unconfirmed; do not replay a potentially executed operation or route it through another connector. Keep the task's progress and report the provider's error, selected Chat/Work surface, and app/extension versions without credentials or private content. A plan label alone does not diagnose a provider refusal.
- CoS returns
TOOL_DISABLED: check Read-only and the named local capability.CALLER_IDENTITY_REQUIREDorWORKER_IDENTITY_LOSTinstead concerns exact caller ownership; neither proves that command execution is globally disabled. - A single
readreportsPLUGIN_DISABLEDorPLUGIN_TOOL_UNAVAILABLE: check which connector received it. Core's built-in file reader belongs to Chat On Steroids Core. A stale request on Plugins can namereadeven though no installed external plugin currently provides it. CoS refuses the call and explains the correct surface; it does not forward it or change permissions. A real disabled external plugin namedreadstill requires that plugin to be enabled. - Extension version mismatch: reload the unpacked companion after updating CoS, then reload the ChatGPT page.
- Models missing: use Reload ChatGPT models. The picker reflects availability in your signed-in account.
UNIDENTIFIED_CALLER: use that conversation in the paired browser so the extension can prove its request identity. CoS does not guess from the active tab.COMPACTION_IN_PROGRESS: let the source chat finish its handoff. Work continues in the replacement conversation.- Linux credential storage unavailable: unlock GNOME Keyring or KWallet, then restart CoS.
- A chat will not stop: Block revokes local tools for that exact conversation. It does not claim to cancel the provider's generation.
Image injections travel as image blocks in the active tool response. The local transcript distinguishes an offered response from a later confirmed receipt. A failure to save an optional image preview does not prevent delivery or leave its message permanently in the composer dock; CoS retains the preview for a history retry. The actual tool result remains the evidence of what was sent.
The MCP connector uses ChatGPT's Developer mode and tunnel interfaces. The companion also observes and automates the browser UI; this is not a public ChatGPT automation API. Your account's terms and policies apply. Do not use it to evade limits or safety controls.
npm ci
npm run dev
npm run verifyRead AGENTS.md before changing the app and CONTRIBUTING.md before opening a PR.
npm run dist:x64 # Windows x64
npm run dist:arm64 # Windows ARM64
npm run dist:mac:x64 # macOS Intel
npm run dist:mac:arm64 # macOS Apple silicon
npm run dist:linux:x64 # Linux x64
npm run dist:linux:arm64 # Linux ARM64Build on the target OS. The release workflow uses native runners for all six targets, checks the packaged runtimes and assembles the complete artifact set with checksums and corresponding native library sources.
MIT licensed. Not affiliated with or endorsed by OpenAI. ChatGPT and Codex are OpenAI trademarks.
After your first Chat On Steroids tool call, open the ChatGPT window created by CoS. A tool approval prompt may be waiting there, with choices such as Allow once, Always allow or Deny. Goal, Loop and agents can appear stuck while ChatGPT is waiting for your decision. Review the requested action and choose in ChatGPT.
If tools disappear, try disconnecting and reconnecting the affected Chat On Steroids plugin in ChatGPT. Then make one tool call and check the opened window for approval again. This is a troubleshooting step, not a guarantee that permissions caused the missing tools.
CoS shows this reminder on the first explicit model-discovery opening and retains it until you acknowledge it. Understood dismisses the reminder; it does not grant tool access or answer the ChatGPT approval prompt. The setup notice stays available afterward.