Trim IDE (VS Code / Cursor)

Not the compressor. Local helper that (1) keeps the Fast Mode proxy ready when Always-on with IDE is on, and (2) posts tab acceptance / AI LOC counters to POST /api/v1/me/events so dashboard charts stay database-backed.

Compression only happens when Cursor / Continue / VS Code Chat / Claude Code send traffic to the local proxy (example http://127.0.0.1:8888/v1). That path is separate from this extension’s Trim Cloud telemetry.

Brand: Marketplace icon + light/dark marks in media/ are generated from the same Trim masters as web/admin (scripts/_gen_site_icons.py). Banners/screenshots: scripts/_gen_ext_marketplace_assets.py.

Two paths

Install the extension but never override Base URL → auto-start + metrics only, not full savings.

Install (recommended)

VS Code Marketplace

1. Extensions view → search Trim IDE by usetrim
2. Install → reload if prompted
3. Complete the Get started with Trim IDE walkthrough (Help → Welcome → Walkthroughs), or follow Configure below

Open VSX (Cursor and other Open VSX clients)

Install Trim IDE (usetrim.trim-ide) from the Open VSX registry when your editor uses Open VSX instead of the Microsoft Marketplace.

Sideload VSIX (air-gapped / pre-publish)

cd extensions/trim-ide
npm ci
npm test
npm run package

Then Extensions: Install from VSIX and select trim-ide-*.vsix.

Live store listing requires operator publish (PUBLISH.md + PATs). Sideload works without that.

First-run checklist

Mental model: Always-on = auto-start preference · Trim API key = Trim Cloud login · Hardware ID = this editor install may use that key.

Configure

1. Settings → Trim: Api Url → your API origin (e.g. https://api.use-trim.com)
2. Command palette → Trim: Copy Hardware ID → Dashboard → Settings → API keys → Register device → paste → agent IDE (never paste a CLI/trim login fingerprint)
3. Command palette → Trim: Set API Key (Trim Cloud key from Dashboard → Settings → API keys)
4. Leave Trim: Auto Start With Ide on follow (uses the cloud preference), or set on / off for a local override
5. Optional: auto-flush (package default 0 = off; pick a value inside cloud IDE_AUTO_FLUSH_* bounds), document LOC tracking, workspace UUID, HTTP timeout

UI labels load from GET /api/v1/public/ide-chrome (site_messages). On first install with no network, the extension stays inactive (fail-closed) and logs to Output → Trim. After a successful chrome sync, a last-known-good cache keeps the UI working offline.

Cloud calls send Authorization, X-Hardware-UUID (IDE hash), and X-Trim-Agent-Id: ide. See Device binding.

Always-on with IDE

• On activate: if the preference is on, health-check the local proxy; start trim if needed
• If a healthy proxy already owns the port, attach (no double-bind)
• Spawns trim start only - never Deep Mode or trim compress on IDE open
• While the IDE stays open, re-checks the preference so a dashboard uncheck can stop auto-start
• Fail soft: proxy start failure does not brick the IDE
• The browser cannot start Trim; this extension (and/or CLI daemon) is the local enforcer

Settings

Example settings when enabling LOC estimates:

{
  "trim.apiUrl": "https://api.use-trim.com",
  "trim.autoFlushSeconds": 30,
  "trim.trackDocumentEdits": true,
  "trim.minLinesForAiHeuristic": 3
}

30 above is an example within cloud IDE_AUTO_FLUSH_* bounds. The packaged default is 0 (off).

Behaviour

• Secret Storage for the API key (never settings.json)
• AbortController timeouts + redirect: "error" (no Bearer leak on redirects)
• URL parse + http/https only; path join via URL; Accept: application/json
• User-Agent: TrimIDE/<version>; X-Client-Version: trim-ide/<version>; X-Trim-Agent-Id: ide
• Single-flight flush; persist pending counters; best-effort flush on deactivate
• Clear counters only after successful HTTP response (subtract snapshot)
• Quota exhausted upgrade prompt uses /api/v1/me/quota + 402 bodies; skipped when the Service reports unlimited=true
• Output channel for diagnostics
• Internal inline-suggest command hidden from the command palette
• Getting Started walkthrough + localized package.nls.* (en, es, de, fr, ja, zh-cn, pt-br)

Publish (operators)

1. Create/verify Marketplace publisher usetrim and Open VSX namespace
2. Store GitHub secrets VSCE_PAT and OVSX_PAT
3. Run workflow Trim IDE extension → Run workflow with publish=true, or publish a GitHub Release

CI packages on every change under extensions/trim-ide/. Publish is fail-closed when PATs are missing (job succeeds with a skip notice).

Limitations

• Cursor does not expose a stable public API for every ghost-text show/accept, so counts use explicit commands plus optional edit heuristics
• VS Code Chat Agent with a Custom Endpoint is not a guaranteed Trim path; prefer Continue for agent-style edits
• Full composer token savings still require the IDE Base URL to point at the local Trim proxy
• Marketplace / Open VSX one-click install depends on publisher release; VSIX sideload works without that
• Listing screenshots may be brand placeholders until replaced with live IDE captures

Uninstall

1. Command Palette → Trim: Clear API Key (clears Secret Storage + local extension state)
2. Command Palette → Extensions → uninstall Trim IDE
3. On the machine CLI: trim uninstall (see docs Uninstall)