---
name: install-codex-cockpit
description: Install or update the Codex Cockpit desktop quota dashboard on Windows or macOS from verified releases or supplied source, and verify first launch. Use when a user asks to install Codex Cockpit or Codex 驾驶舱, not to install the Codex agent itself.
---

# Install Codex Cockpit

Help the user reach a working local desktop installation. Respond in the user's language. Default to local-only use; app installation does not authorize data synchronization, account changes, Skill registration or publishing anything.

## Establish the source and target

- Detect OS, CPU architecture, available disk space and any existing Codex Cockpit installation. Linux is not validated; explain that boundary rather than attempting an unsupported system installation.
- Use the source directory or release explicitly provided by the user. The intended upstream is `HouSiyuan2001/codex-cockpit` on GitHub, but repository and release availability must be verified live before use. Before publication, a supplied local checkout/archive is sufficient. Do not substitute Quota Float, an unrelated fork or a similarly named binary if the intended source is unavailable.
- Resolve the source root from the supplied directory, not from this Skill's installed location. Read that source's `README.md` or `README.zh-CN.md`, `PRIVACY.md`, and `src-tauri/tauri.conf.json`. Confirm `package.json` and `src-tauri/Cargo.toml` belong to the same app/version. The public application identifier is `io.github.housiyuan2001.codex-cockpit`.
- Record the commit when Git metadata exists; otherwise record the supplied archive/source identity without inventing provenance. Preserve dirty source checkouts. Never switch branches, reset files or overwrite an existing checkout to make installation easier.
- Explain the chosen route and installation destination. Detect an existing app before replacement and obtain confirmation if replacement was not requested. Preserve app data and unrelated applications. Do not migrate another app identifier's preferences implicitly.

## Choose an installation route

Prefer a verified, matching release when available and not contrary to the user's choice. Check exact OS/architecture, release provenance, supplied checksums and actual signing/notarization status. A locally computed hash alone does not authenticate a download. If no trusted matching artifact exists, use the supplied source or request an exact source; do not invent a download URL.

For a source build, inspect installed prerequisites first:

```text
node --version
npm --version
rustc --version
cargo --version
```

The source expects Node.js 22+ and Rust stable. Check the current [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/) for the detected platform before adding missing system dependencies. macOS needs Xcode command-line tools; Windows needs Microsoft C++ Build Tools with the C++ desktop workload, a Windows SDK and WebView2. Use existing compatible tools. Explain any required privileged/system installation and let the user handle interactive security or administrator prompts. Do not run an unreviewed remote shell installer or disable security controls.

Run from the verified source root, checking each exit code before the next command:

```sh
npm ci
npm run version:check
npm test
npm run build
cargo test --manifest-path src-tauri/Cargo.toml
npm run tauri -- build
```

`npm ci` executes dependency lifecycle scripts: use it only after establishing source trust. Do not update lockfiles or upgrade dependencies just to pass installation. `npm run dev` is a synthetic browser preview, not the desktop app. `npm run tauri -- dev` is a development session, not a persistent installation.

On Windows, use the installed Visual Studio developer environment if compiler discovery fails; do not assume the hard-coded Visual Studio path in `build-windows.cmd` matches the user's machine. Avoid macOS-only shell commands on Windows. If a build runs out of space, report the exact generated cache location; do not delete source, app data or unrelated caches without authorization.

## Install and verify

- Locate actual build output (normally `src-tauri/target/release/bundle/`, unless Cargo's target directory was customized). Do not guess versioned filenames or report a `--no-bundle` executable as an installer.
- macOS: use the matching `.app`/`.dmg`, installing to the user-approved Applications directory. Windows: run the matching generated `.msi` or NSIS installer with its normal interactive flow. Do not silently change all-user/per-user installation scope.
- If Gatekeeper, SmartScreen, Defender, signing or notarization blocks the artifact, stop and report the precise blocker. Do not remove quarantine, disable antivirus, change execution policy or bypass a warning as a routine fix.
- Before first launch, explain that the app reads existing local provider sign-in/usage sources and contacts provider quota services and public reset endpoints. It does not need the user's token pasted into the Agent. Ask the user to sign in normally through Codex if necessary; do not open, print, copy or transmit auth files, credentials or raw sessions yourself.
- Launch only the verified installed app. Confirm its identity/version and visible floating window or tray. Check quota loading through the app when authorized and available, without capturing sensitive screenshots. If UI access is unavailable, ask the user to check and mark launch/quota verification pending. A process existing is not proof that quota loaded.
- Do not configure autostart or sync unless requested. Preserve existing preferences on updates; never claim an existing automatic-sync preference is off without checking it. If an update will resume previously configured sync, disclose that before launch.

## Optional sync handoff

Only if the user requests synchronization, read `docs/SETUP.md` and `PRIVACY.md` from the verified source. Use a separate user-chosen private data repository, never the public source repository. Confirm its visibility and the shared data scope before the first upload or enabling automatic sync. Person/device groups are not access control. If visibility cannot be verified, do not upload. Do not create repositories, invite people or change permissions merely because app installation was requested.

## Completion receipt

Report source version/commit or archive identity, OS/architecture, installed path, build/install/launch/quota status separately, and any blocker. State whether sync was left untouched or explicitly configured. Do not report success from tests alone. Keep paths and diagnostics local; no telemetry, issue submission, remote push, credential output or real usage records are part of this workflow.