# Claude Code Desktop: setup, limits and how it differs from the CLI

> AI Release · @ai_release1 · https://ai-release.org/guides/claude-code-desktop-ustanovka_en.html

## TL;DR
- Time to complete: ~25 minutes
- Difficulty: Basic
- You will need: Windows 10 or newer; the `Capri-Setup.exe` installer from the Capri-AI GitHub repository; a Claude account (Pro/Max) or an API key; Claude Code 2.1.232 or newer as the engine; optionally a Linux machine with Bun if you want to remove the status-line token overhead.

## Requirements and setup
![Illustration: Requirements and setup](https://ai-release.org/guides/img/claude-code-desktop-ustanovka-en-1.jpg?v=1793608969)

- **OS:** Windows 10 or newer — that is the stated requirement of the Capri-AI desktop wrapper, the only desktop (non-terminal) route covered by our sources. An official "Claude Code Desktop" build is **not** documented in these materials: verify its availability in the vendor documentation before planning around it.
- **Engine:** Claude Code 2.1.232 or newer. From build 2.1.232 the status-line feature that summarises background agents is enabled by default and has no toggle.
- **Account:** your own Claude Pro/Max subscription or an API key — Capri-AI routes tasks to Claude Code, Codex or Antigravity using one of these.
- **Do not install:** the Claude Code for VS Code bundle build **2.1.313** from the Cursor Marketplace. Phorion found a baked-in SSH backdoor in that bundle; Cursor removed the release from the marketplace and pulled 2.1.313 from NPM and the VS Code registry.
- **Disk space, package name of the HUD installer, exact pricing:** not stated in our sources — check the repository README and vendor documentation.

If you are still choosing an engine rather than installing one, start with [AI for programmers: coding assistants in 2026](https://ai-release.org/guides/ii-dlya-koda.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## Step 1. Choose the desktop route and check the machine before installing
![Illustration: Step 1. Choose the desktop route and check the machine before installing](https://ai-release.org/guides/img/claude-code-desktop-ustanovka-en-2.jpg?v=1793608972)


**What to do:** decide between two documented routes, then verify the machine is clean before you give any wrapper shell access.

| Route | What it is | Terminal needed | What you get |
|---|---|---|---|
| Capri-AI | Native Windows desktop app, `Capri-Setup.exe`, MIT licence, 5 commits in the repo | No | Tasks go to Claude Code / Codex / Antigravity; file and shell access behind confirmation prompts |
| Claude Code + Spark HUD | Terminal engine plus an animated HUD drawn above the terminal | Yes | Live context window, Max plan limits (5-hour and 7-day) with burn-rate forecast, cost, subagents, all open Claude windows |

```powershell
winver
claude --version
Get-Content "$env:USERPROFILE\.ssh\authorized_keys" -ErrorAction SilentlyContinue
Get-FileHash .\Capri-Setup.exe -Algorithm SHA256
```

**Example:** `winver` opens a dialog reading "Windows 10" or "Windows 11"; `claude --version` prints a build number — anything from `2.1.232` upward has the status-line feature on by default. The `Get-Content` command prints your public keys or nothing at all on a fresh machine.

**Why:** the 2.1.313 incident shows a bundle can execute at module load, *before* `activate`, and append an Ed25519 key to `~/.ssh/authorized_keys` with `0700`/`0600` permissions. Capri-AI is open source under MIT but has only 5 commits, so treat it as young code and check the hash against the release notes before running it.

**How to check:** the `authorized_keys` output must contain only keys you added yourself. If a line of the form `ssh-ed25519 AAAAC3Nza... you@host` appears that you cannot account for, stop and rotate your SSH keys.

## Step 2. Install the wrapper and route a task to Claude Code

**What to do:** run the installer from PowerShell, start the app from the Start menu shortcut, pick Claude Code as the engine, attach your account or API key, then send one test task and watch the confirmation prompt.

```powershell
cd $env:USERPROFILE\Downloads
.\Capri-Setup.exe
```

**Example:** after installation a Capri-AI shortcut appears in the Start menu. In the app, choose `Claude Code` as the engine, paste your API key or sign in with your Pro/Max account, and send the task `list the files in this folder`. The app asks for confirmation before it touches the filesystem — that prompt is the file/shell gate described in the project description.

**Why:** the desktop app is a front-end only. The work is still executed by Claude Code on your account, so the session and weekly limits you will measure in Step 3 are exactly the same as in the terminal. If you plan to fan work out to subagents, the `aaronyi97/claude-pro-pool` project distributes subagents across your own Pro/Max accounts by remaining quota and switches account automatically when one hits the quota — the same pattern described in [Claude Code Agent Teams: running a team of coding agents](https://ai-release.org/guides/claude-code-agent-teams-komanda-agentov.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

**How to check:** the shortcut is present, a task submitted through the GUI returns output, and no file or shell action happens without an explicit confirmation. If a task edits files with no prompt, stop and review the app's permissions before continuing.

## Step 3. Measure limits and confirm the desktop view matches reality
![Illustration: Step 3. Measure limits and confirm the desktop view matches reality](https://ai-release.org/guides/img/claude-code-desktop-ustanovka-en-3.jpg?v=1793608975)


**What to do:** record your limits from both tools and compare them with what the desktop app actually consumes.

```text
In a terminal running Claude Code, inside an open session:
/usage
```

**Why:** `/usage` shows the remaining quota only inside the session you have open and only for one account. It cannot tell you what is left in the weekly window while the session is closed, so you have to count two constraints — the 5-hour session and the weekly window — yourself. Spark HUD (GitHub `Mel0nidas/spark-hud`) is the overlay that adds the missing view: live context window, Max plan limits for the 5-hour and 7-day windows with a burn-rate forecast, cost, subagents and all open Claude windows. Install it from its README — the exact install command is not in our sources.

On Linux builds tested at 2.1.257–2.1.312, roughly 16.4% of Claude Code spend and 19.7% of API requests go to the background status-line summary, 96% of that amount on Opus. There is no toggle for it since 2.1.232; the documented workaround is a Bun preload of about 80 lines:

```bash
BUN_OPTIONS="--preload ./claude-preload.js" claude
```

**How to check:** open a session, run `/usage`, and write down both numbers — the 5-hour figure and the weekly figure. Close the session and run `/usage` again: for the weekly window you will have no reading. In Spark HUD the context and cost values must change after every prompt; if they stay frozen, the HUD is not attached to the session.

Checklist before you trust the setup:

- [ ] `/usage` read inside an open session, both limits recorded
- [ ] HUD shows context window, cost and Max windows for a Pro/Max plan
- [ ] Status-line overhead accounted for on builds 2.1.232+
- [ ] No unexpected key in `~/.ssh/authorized_keys`
- [ ] Engine version noted, so you can re-check after an update

## Troubleshooting

**Problem. PowerShell will not start the installer.**
- Error: `Capri-Setup.exe : The term 'Capri-Setup.exe' is not recognized as the name of a cmdlet, function, script file, or operable program.`
- Cause: PowerShell does not execute binaries from the current directory unless the path is explicit.
- Solution: prefix the name with `.\`: `.\Capri-Setup.exe`, or pass the full path `& "$env:USERPROFILE\Downloads\Capri-Setup.exe"`.

**Problem. An unknown SSH key exists on the machine.**
- Error: a line of the form `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... user@host` in `~/.ssh/authorized_keys`.
- Cause: the Claude Code for VS Code bundle build 2.1.313 from the Cursor Marketplace wrote an Ed25519 key into `authorized_keys` at module load, before `activate`. Note that on macOS the malware also breaks itself because of a bug in its own code.
- Solution: delete the line, rotate your SSH keys, uninstall 2.1.313, confirm the removal with `Get-Content "$env:USERPROFILE\.ssh\authorized_keys"`, and check permissions on the file (`0600`) and on `~/.ssh` (`0700`).

**Problem. You cannot plan the week from `/usage`.**
- Error: no output for the weekly window once the session is closed — the indicator is scoped to the open session and one account.
- Cause: `/usage` reports remaining quota only inside the current session.
- Solution: log both constraints (5-hour session, weekly window) at the start and end of each block, and use Spark HUD's 5-hour and 7-day forecast for the trend. If the preload workaround stops working after a Claude Code update (a Bun error mentioning the preload module is not found), re-apply the hook or drop it — it was tested only on Linux at 2.1.257–2.1.312.

If you keep per-project instructions for these agents, the folder layout in [ICM in practice: a folder structure that keeps agents manageable](https://ai-release.org/guides/icm-praktika-struktura-papok-agenta.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide) prevents the same prompt work from being redone in every new session.

## Summary and next steps
Install the wrapper, route one task through it, and confirm that the file/shell confirmation gate actually fires. Then measure the 5-hour and weekly limits yourself, since `/usage` alone will not show them outside an open session.

## FAQ

**Is there an official Claude Code desktop app?**
An official desktop build is not covered in our sources — check the vendor documentation. The documented desktop route here is Capri-AI, a Windows shell that drives Claude Code, Codex or Antigravity.

**Does a desktop wrapper give me different limits from the terminal?**
No. The work still runs on your Claude account, so the two constraints — a 5-hour session and a weekly window — apply identically.

**Why does the desktop/terminal panel show a short agent summary every few seconds?**
Claude Code sends the full background-agent transcript to its own model every ~30 seconds to produce a 3–5 word label. On the tested builds this consumed 16.4% of spend and 19.7% of API requests, with 96% of that amount on Opus.

**Is Capri-AI safe to run?**
It is open source under MIT with only 5 commits, and every file or shell action goes through a confirmation prompt. Verify the installer hash yourself and check `~/.ssh/authorized_keys` afterwards — the 2.1.313 case shows why that check matters.