# Install Quokka for an Agent This is an execution protocol for a local coding Agent. Read it completely before changing configuration. A Chinese-speaking user should need only this Prompt: > 请完整阅读 https://csagent.hongan.live/install，并按照文档为我安装 Quokka。 > 优先复用并验证现有授权；仅在从未授权或明确需要重新授权时完成浏览器登录。 > 完成 MCP 连接、Plugin/Skill 安装和只读验证后再结束；不要克隆 CSAgent 仓库。 Equivalent English Prompt: > Please fully read https://csagent.hongan.live/install and install Quokka for > me. Reuse and verify existing authorization first; complete browser login only > when this host has never authorized Quokka or Codex explicitly requires > reauthentication. Complete MCP connection, Plugin/Skill installation, and > read-only verification before stopping. Do not clone the CSAgent repository. ## Required outcome Connect this Agent to the hosted Streamable HTTP MCP server at `https://csagent.hongan.live/mcp` and reuse a working OAuth authorization. Complete GitHub browser login only under the explicit conditions in section 2. For Codex, install the official `quokka-batch-support` Plugin, which owns both the Skill and the MCP declaration while displaying **Quokka Customer Service** to users. For Claude Code, install the `quokka-customer-service` Skill and its user-scoped MCP connection. Do not clone CSAgent, install Node.js packages, start a local server, or ask for Stripe, Chatwoot, database, GitHub, or Quokka tokens. The Agent's MCP client stores the OAuth credential after the user signs in. One-hour access tokens are renewed with rotating refresh tokens; Plugin updates and Quokka deployments must not remove that credential. The GitHub account must be a current member of the configured Hongan GitHub organization. ## Safety contract - Never ask the user to paste a token, authorization code, callback URL, or provider credential into chat or a file. - During installation, call only public health/discovery endpoints, MCP initialization/tool listing, and `quokka_read_memory`. - Do not call `quokka_fetch_emails`, list or read customer cases, mutate a case, approve or execute actions, send replies, refund, or cancel. - Preserve unrelated MCP and Skill configuration. If a `quokka` MCP entry uses another URL or a static Authorization header, report the non-secret conflict and ask before replacing it. ## 1. Detect one client Install only for the Agent executing this document unless the user explicitly asks for both. - Codex session with a `codex` executable: follow section 2A. - Claude Code session with a `claude` executable: follow section 2B. - Another client: add the remote Streamable HTTP URL without a static header, start its standards-based MCP OAuth login, and install the Skill from `https://csagent.hongan.live/install/quokka/SKILL.md` in its documented user Skill directory. First perform this public, read-only check: ```bash curl --fail --silent --show-error https://csagent.hongan.live/api/health ``` Require HTTP 200 and an `"ok":true` response. A failure is a service or network problem; it is never a reason to clone the repository. ## 2A. Codex Use the official marketplace package. It contains the Skill and the OAuth-enabled `quokka` MCP declaration, so do not create a second MCP entry and do not download the Skill as an unrelated file. Inspect first: ```bash codex plugin marketplace list codex plugin list codex mcp list --json ``` If `quokka-support-skills` is absent, add it. Otherwise upgrade its snapshot. Before installing the versioned Plugin, remove any same-URL legacy global override that passed the pre-install conflict check: ```bash codex plugin marketplace add honganai/quokka-skill-marketplace --ref main codex plugin marketplace upgrade quokka-support-skills codex mcp remove quokka ``` `codex mcp remove` only removes a global MCP configuration; it does not run `codex mcp logout` or delete OAuth credentials. It is a no-op when no global entry exists. Removing it before `plugin add` is required because the Plugin's `ON_INSTALL` policy may start OAuth immediately. Then install or update the Plugin and verify the effective connection: ```bash codex plugin add quokka-batch-support@quokka-support-skills codex mcp list --json ``` Capture only the non-secret connection state from `codex plugin list --json` and `codex mcp list --json` before the upgrade, then run both commands again afterward. If Quokka was connected before the upgrade, require it to remain connected afterward and require exactly one enabled MCP named `quokka`. Never inspect, copy, hash, or print the credential store during user installation. Skip only the marketplace-add command when the correctly sourced marketplace already exists. Upgrades must use this CLI flow; do not uninstall/reinstall from the Codex Desktop Plugin UI because its `ON_INSTALL` policy can start a new OAuth flow. If the pre-install inspection found a `quokka` entry with a different URL or a static Authorization header, report only that non-secret conflict and stop. The Plugin-provided `quokka` must become visible, enabled, unique, and use `https://csagent.hongan.live/mcp`. Stop before login if it does not. This migration is required because a legacy global entry takes precedence over the Plugin and may retain OAuth parameters that current Codex versions handle differently. The current Plugin deliberately omits `oauth_resource`: Codex discovers the canonical value from protected-resource metadata, while an explicit override can make affected clients send the same `resource` twice. Before any login, require both OAuth metadata endpoints to return successfully: ```bash curl --fail --silent --show-error https://csagent.hongan.live/.well-known/oauth-protected-resource/mcp curl --fail --silent --show-error https://csagent.hongan.live/.well-known/oauth-authorization-server ``` Start login once only for a confirmed first installation with no prior Quokka authorization, or when Codex explicitly reports `reauthenticationRequired` or the token endpoint returns `invalid_grant`: ```bash codex mcp login quokka ``` Wait for the user to approve the Quokka consent page and complete GitHub login. The client stores both access and refresh state; neither the user nor Agent copies it. Never run `codex mcp logout`, remove the working `quokka` entry, or delete the credential store as part of an install or upgrade. Start one new Codex task if the current task does not reload the newly installed Plugin. `Not logged in` / `not_logged_in` by itself never triggers login because a metadata, DNS, or TLS failure can produce the same status. ## 2B. Claude Code Install the standard Skill directly in Claude Code's personal Skill directory. As with Codex, stop on a differing existing Skill rather than overwriting it: ```bash skill_dir="${HOME}/.claude/skills/quokka-customer-service" skill_tmp="$(mktemp -d)" curl --fail --silent --show-error \ https://csagent.hongan.live/install/quokka/SKILL.md \ --output "${skill_tmp}/SKILL.md" if test -f "${skill_dir}/SKILL.md" && ! cmp -s "${skill_dir}/SKILL.md" "${skill_tmp}/SKILL.md"; then echo "Existing quokka-customer-service Skill differs; stop before replacing it." >&2 exit 2 fi mkdir -p "${skill_dir}" install -m 0644 "${skill_tmp}/SKILL.md" "${skill_dir}/SKILL.md" ``` Install the `invoice-reissue` add-on Skill beside it. Its script must land in `scripts/` next to its `SKILL.md` or the Skill's own commands will not resolve: ```bash inv_dir="${HOME}/.claude/skills/invoice-reissue" mkdir -p "${inv_dir}/scripts" curl --fail --silent --show-error \ https://csagent.hongan.live/install/quokka/invoice-reissue/SKILL.md \ --output "${inv_dir}/SKILL.md" curl --fail --silent --show-error \ https://csagent.hongan.live/install/quokka/invoice-reissue/scripts/update_invoice_pdf.py \ --output "${inv_dir}/scripts/update_invoice_pdf.py" python3 -c "import fitz" 2>/dev/null \ || echo "invoice-reissue needs PyMuPDF: pip install 'pymupdf>=1.26'" ``` Report the PyMuPDF line if it prints; do not install the package without the user agreeing. The rest of Quokka works without it. Inspect with `claude mcp get quokka`. If no entry exists, add the OAuth-enabled server in user scope: ```bash claude mcp add --transport http --scope user \ quokka https://csagent.hongan.live/mcp ``` If an entry exists with the same URL and no static Authorization header, keep it. Otherwise stop and report the exact non-secret difference before replacing anything. Reuse and verify an existing Claude authorization before starting login. As with Codex, `Not logged in` alone is not evidence that credentials are missing. Require both OAuth metadata endpoints to be reachable, then start browser authentication only when the entry was just created and this host has never authorized Quokka, or Claude explicitly reports reauthentication / an `invalid_grant`: ```bash claude mcp login quokka ``` Wait for the user to approve the Quokka consent page and complete GitHub login. On Claude Code older than 2.1.186, use the in-session `/mcp` menu, select `quokka`, and choose **Authenticate** instead, but only under the same explicit conditions. Start one new Claude Code session only if the current session does not discover the new personal Skill or connection. ## 3. Verify without customer-data access Complete every check before claiming success: 1. The current Agent shows a connected MCP server named `quokka`. 2. Its tool list contains `quokka_read_memory`, `quokka_list_cases`, and `quokka_reprocess`. 3. Call `quokka_read_memory` with `{"path":"skills/cs-workflow.md"}` and require a successful, non-empty response. 4. Confirm the expected Skill is discoverable: `quokka-batch-support` on Codex or `quokka-customer-service` on Claude Code. It must contain the hard boundary that batch preparation never calls `quokka_execute_actions`. 5. Confirm the `invoice-reissue` Skill is discoverable and that `python3 --help` prints usage, or report that PyMuPDF is missing (`pip install 'pymupdf>=1.26'`). Never install the package without the user agreeing — the rest of Quokka works without it. 6. Confirm no installation step fetched mail, accessed a case, wrote customer data, approved an action, or executed an action. Writing files or MCP configuration alone is not completion. A reused or newly completed OAuth authorization, live MCP connection, Skill discovery, and the memory read must all succeed. ### 3A. Codex automatic new-session verification First check whether this task already has the Quokka tools and Skill loaded. If it does, perform the five checks above directly in this task; do not start an additional Codex process or repeat a successful memory read. If this task cannot see the newly installed Plugin, run the published helper once. It starts a temporary read-only verification session and passes the configuration arguments exactly, without nested shell quoting: ```bash verify_script="$(mktemp)" curl --fail --silent --show-error \ https://csagent.hongan.live/install/assets/verify-codex.sh \ --output "$verify_script" && sh "$verify_script" ``` Do not reconstruct the helper's command using `eval`, `zsh -lc`, or generated configuration overrides. It preserves the user's selected model and reports `verification_elapsed_seconds` plus a sanitized result. It never logs raw MCP responses. Except for the single discovery retry described below, stop on failure and report the result; do not experiment with models or approval overrides. The `writes` approval mode depends on Quokka's MCP annotations: only tools the server explicitly marks read-only can run without a write confirmation. If the result is `PLUGIN_NOT_LOADED` or `MCP_NOT_LOADED`, repeat the complete command once. Do not retry other failures automatically. Only a successful direct verification or `QUOKKA_VERIFY_OK` completes Codex installation. For Claude Code, perform the five checks above in a new session only when the current session has not discovered the newly installed Skill or MCP. ### Continue customer work in a task with loaded tools A successful helper verifies the installation, but it cannot add tools to the parent task. If Quokka tools are absent from the parent task, finish installation and tell the user to start a new task with the Quokka Plugin for customer work. Do not route case creation, enrichment or preparation through repeated `codex exec` children. Never reuse the read-only installation verifier for customer writes or change approval settings to make those writes run. ## 4. Diagnose one failure - Browser rejects the GitHub account: it is not an active member of the allowed organization, the organization has not approved the OAuth App, or `read:org` was not granted. Do not retry repeatedly. - OAuth metadata or TLS failure: this is a network/discovery failure. Preserve the Plugin, MCP entry, and credential, then report the failing endpoint; do not log out or replace the connection. - `invalid_grant` or explicit reauthentication after refresh: login is no longer usable because the refresh grant expired, was revoked, or cannot be bound to its registered client. Run one normal OAuth login; do not reinstall or delete credentials first. - `invalid_target` with `The exact Quokka MCP resource is required`: do not repeat login. Upgrade/install Plugin v0.2.3 or newer, confirm the effective MCP has no manually configured `oauth_resource`, run the legacy global migration in section 2A, then retry login once. - HTTP 401 without `resource_metadata`: production is running an older build. Report the endpoint and header; do not request a legacy token. - MCP entry connects but tools are absent: reload once or start a new task, then inspect MCP status. - `/install` returns HTML or an asset returns 404: report the URL and status; do not fall back to a repository checkout. - Any provider credential is requested: stop because the installation path is wrong. Provider access belongs only to the hosted server. Use these stable error codes in the completion report: - `OAUTH_REFRESH_FAILED`: the refresh grant is expired or revoked; log in once, but do not reinstall. - `PLUGIN_NOT_LOADED`: the fresh Codex session did not load the Plugin; retry one fresh session. - `MCP_NOT_LOADED`: the fresh session did not discover `quokka`; check Plugin enabled state and retry one fresh session. - `MCP_AUTH_UNAVAILABLE`: distinguish discovery/network failure from explicit `invalid_grant`; never log out as a generic repair. - `READ_ONLY_VERIFY_FAILED`: preserve Plugin, MCP, and credentials and report the failed read-only layer. ## Completion report Return exactly these sanitized fields: ```text product: Quokka Customer Service client: plugin_or_skill: mcp: quokka, connected, unique authorization: reused | new_login read_only_verification: passed new_task_required: ``` Never include a token, code, state, callback query, credential fingerprint, memory content, customer content, or any token-derived value. Suggested first task after installation: > Use the Quokka batch-support Skill to prepare every case from yesterday in my > timezone up to, but not including, action execution.