# Use Cloakgpt

> Use, update, or completely uninstall CloakGPT when the user asks an agent to operate their own ChatGPT browser session, signed in or signed out, manage persistent conversations or page settings, preserve returned Markdown and sources, update the packaged CLI, or remove CloakGPT data; not for ordinary questions the agent can answer directly.

- Skill: `koukeneko/use-cloakgpt` (Agent Skill)
- Install (CLI): `npx skillmds@latest add koukeneko/use-cloakgpt`
- Raw SKILL.md: https://api.skillmd.com/api/skills/koukeneko/use-cloakgpt/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: KoukeNeko (https://skillmd.com/u/koukeneko)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/koukeneko/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:

```sh
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:

```sh
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:

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

Windows:

```powershell
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.