Use Cloakgpt

Use CloakGPT

Use CloakGPT as a user-authorized browser client. Sending a prompt changes an external ChatGPT conversation, so submit only messages the user requested.

Trust and security boundaries

• The canonical source is https://github.com/KoukeNeko/CloakGPT. Use only its official installers and GitHub Releases. The installers download the selected platform asset and its .sha256 file, then verify the checksum before installation. macOS release assets are Developer ID signed and notarized; Windows assets are not currently code-signed and may show a platform warning.
• CloakBrowser is a separately downloaded external binary with its own license and trust boundary. Do not describe it as bundled into CloakGPT or covered by CloakGPT's MIT License.
• CloakGPT intentionally controls the user's own browser profile and can send messages to ChatGPT, whether or not that profile is signed in. Treat an agent allowed to execute it as authorized only for the operations the user requested. Never use it to bypass account controls.
• A persistent session ID is a local conversation selector, not a ChatGPT credential or the daemon authentication key. The separate daemon key remains in the local CloakGPT data directory and is never printed by normal commands. Keep session IDs out of final answers because they are local conversation metadata, even though they are not authentication secrets.

Choose the operation

• For repeated messages in one agent task, run cloakgpt session open once, capture its local conversation ID from stdout, and retain it for later turns. The MOTD and status are on stderr.
• Send every persistent turn with cloakgpt ask <question> --session <ID>. The first message creates a ChatGPT conversation; later messages reopen its saved conversation URL. Each request closes its own page after the complete answer, while the session ID remains reusable.
• Use cloakgpt ask <question> without a session for a one-shot new conversation. Every ask uses the shared daemon, so concurrent agent and terminal calls use separate pages instead of competing for the browser profile. A one-shot request uses a temporary page and leaves existing persistent sessions intact. Do not stop the daemon merely to start a new one-shot conversation.
• A one-shot ask also works on a signed-out profile; persistent sessions do not. A signed-out conversation is not addressable the way --session requires, so a session request on a signed-out profile fails before sending anything. Do not ask the user to sign in for a one-shot question.
• Prefer the installed cloakgpt command. In a source checkout where it is not installed, use that checkout's virtual-environment Python with cloakgpt.py.
• Pass the question as one argument. Use the shell's safe argument quoting; do not interpolate the question into executable shell syntax.

Preserve page settings by default

Omit --model and --reasoning unless the user explicitly requests them. Omission preserves ChatGPT's current page settings.

A signed-out page has no model or reasoning controls, so ChatGPT chooses for itself and both options are rejected rather than ignored; the reported page status reads signed-out default. If the user needs a specific model or reasoning level, ask them to run cloakgpt login first.

Supported model values are:

• gpt-5.6-sol
• gpt-5.5
• o3

Supported reasoning values are:

• fast
• medium
• high

Pass --timezone <IANA timezone> when the user's timezone is known and needs to be explicit. Do not guess a timezone. The CLI's configured default applies when the option is omitted.

Examples:

cloakgpt ask "Summarize the tradeoffs."
cloakgpt session open
cloakgpt ask "Now give me a concrete example." --session SESSION_ID --reasoning high
cloakgpt ask "What is the weather today?" --timezone Asia/Taipei

Run and collect the response

• Keep the default headless mode for normal work. For a persistent session, add --headed only to session open; this selects the mode for each on-demand browser request and cannot change while its daemon is running.
• Reuse one session ID throughout the same agent task. Do not open multiple sessions speculatively or stop the shared daemon.
• Different agents or independent tasks should use different session IDs. Distinct sessions and one-shot requests may generate concurrently without a CloakGPT page limit. Concurrent calls sharing one session ID remain FIFO so a follow-up cannot overtake the preceding turn.
• A session stores a validated conversation URL, not a live page. Every turn restores that URL in a request-owned page and closes that page after collecting the full answer. Other active pages remain open; Chromium closes only after the final active or waiting request finishes. Do not describe it as the exact same browser page or process.
• Do not impose an arbitrary response timeout. ChatGPT generation and web search can take an unknown amount of time. Keep waiting while the process reports progress; stop with Ctrl+C only at the user's request or when cancellation is otherwise required. CloakGPT bounds inactivity, not total time: a page that shows no progress at all releases itself and reports that the prompt was sent but completion could not be confirmed, while a long answer that keeps making progress is never cut off. Interrupting disconnects the client, and the daemon then cancels that request and closes its page, so the message may already have reached ChatGPT; check the conversation before resending it.
• In ordinary text mode, read progress from stderr and the completed answer from stdout. Do not return [status] lines as part of the answer.
• For agent-driven calls, prefer cloakgpt ask ... --output jsonl. Every status callback is immediately flushed as one stdout line. Parse every JSON line by type: surface or retain each status.message in order, use only result.answer as the completed response, and treat error.message plus the nonzero exit as failure. Run JSONL mode directly in the foreground; do not pipe it through grep, tail, command substitution, or a filter that keeps only the result because that hides live status. When the runtime has a line-oriented stdout monitor, use it to consume the unfiltered command; Claude Code's Monitor is one example. If such a monitor is unavailable, keep waiting in the foreground instead of assuming that changing streams can force the runtime UI to update.
• Preserve the returned Markdown. When the answer contains ## Sources, retain those links and do not invent, rewrite, or remove citations.
• Report a nonzero exit and its concise error instead of presenting partial output as a completed ChatGPT answer.

Recover from setup and session failures

Use the least invasive recovery step:

1. If the cloakgpt command is missing, tell the user to install CloakGPT from its official repository. Do not download an executable from another source.
2. If the browser binary is missing, run cloakgpt browser install.
3. If installation still fails, inspect with cloakgpt browser info --quick or cloakgpt browser doctor, then report the diagnostic and any named environment variable. Do not guess credentials or license values.
4. If a persistent session reports that the profile is signed out, ask the user to complete cloakgpt login in its visible browser window. Do not ask for a login when a one-shot ask would serve the request, because that works signed out. An idle daemon does not hold the browser profile; if a session request is active, wait for it to finish or obtain permission before stopping the daemon. Stopping preserves session IDs and conversation URLs. Never enter, request, or expose their ChatGPT password, cookies, browser storage, or daemon authentication material.
5. If CloakGPT says the browser profile is already in use, or an older build dumps a Chromium error ending in exitCode=21, run cloakgpt daemon status. It succeeds either way: {"running": false} means no daemon exists, which is an ordinary state and not a failure to report or retry. Wait for an active request when it owns the profile; otherwise obtain permission before stopping it. cloakgpt daemon stop refuses while requests are still running and says so; treat that as the request still being alive and wait. cloakgpt daemon stop --force abandons those requests and closes the browser, so use it only for work that can no longer finish and only with the user's explicit approval for that specific loss. If no daemon is running, ask the user to close the CloakGPT Chromium window. Do not delete profile lock files or terminate unrelated Chrome processes.
6. If a command reports that the daemon is running but unreachable, and names its process ID, report that to the user and let them end that process. Do not terminate it yourself.
7. For a headless page-state failure, retry once with --headed only when a visible diagnostic run is acceptable. Persistent sessions require stopping the daemon before changing browser mode; do not stop it without permission.

Update CloakGPT

Checking is read-only and may be done when the installed version matters:

cloakgpt --version
cloakgpt update --check --json

Install an update only when the user requested it or approved the mutation. cloakgpt update preserves the current build's stable or prerelease channel. Use --channel stable, --channel prerelease, or --version TAG only when the user selected that target; --channel and --version are mutually exclusive.

An actual update verifies the downloaded release, stops the daemon, and preserves the browser profile and persistent session records. Wait for an active request before updating. On Windows, the command stages a hidden updater and replacement finishes just after the command exits. Verify the result with cloakgpt --version; if it still reports the old version, retry briefly for up to 10 seconds and report any update failure shown by the next invocation.

Self-update works only for packaged releases. If a source checkout refuses it, do not overwrite files or run git pull across uncommitted changes; report the checkout and update it through its normal Git workflow when authorized. CloakGPT packages a CA bundle and keeps HTTPS certificate verification enabled. For a TLS interception proxy, use a user- or administrator-provided PEM bundle through SSL_CERT_FILE; never disable verification or invent a certificate path. If an older packaged build cannot self-update because its CA bundle is missing, use the authorized official installer to bootstrap the selected release while preserving profile and session data. CloakBrowser is separate. Run cloakgpt browser update only when the user also requested a browser update or a diagnosed compatibility problem requires it.

Completely uninstall CloakGPT

Run a complete uninstall only when the user explicitly requests it. If they have not already confirmed the destructive scope, explain that it permanently deletes the ChatGPT browser profile and cookies, conversation/session state, CloakBrowser downloads and cached license data, the executable, and all installed use-cloakgpt skill copies, then obtain confirmation.

Use the official script from the CloakGPT repository. In a non-interactive agent terminal, add the confirmation flag only after the user has approved the complete removal.

Linux and macOS:

curl -fsSLO https://raw.githubusercontent.com/KoukeNeko/CloakGPT/main/scripts/uninstall.sh
sh uninstall.sh --yes
rm uninstall.sh

Windows:

Invoke-WebRequest https://raw.githubusercontent.com/KoukeNeko/CloakGPT/main/scripts/uninstall.ps1 -OutFile uninstall.ps1
powershell -ExecutionPolicy Bypass -File .\uninstall.ps1 -Yes
Remove-Item .\uninstall.ps1

The script stops the daemon, asks the Agent Skills CLI to find and remove every global use-cloakgpt agent link when available, removes known skill paths as a fallback, and honors the documented CloakGPT directory environment overrides. Report any safety refusal or skill-removal warning; do not claim a complete uninstall while one remains. Because the current skill is deleted during the operation, finish verification from these already-loaded instructions and tell the user to restart their agent so its in-memory skill list is refreshed.

Do not run browser clear-cache, log out, delete the profile, or overwrite CLOAKGPT_DATA_DIR unless the user explicitly requests that destructive state change. Do not commit or display browser profiles, conversation state, cookies, signing material, or secret environment variables.