v4.0.3

v4.0.3 — see RELEASE_NOTES_v4.0.3.md

v4.0.2

v4.0.2 — see RELEASE_NOTES_v4.0.2.md

v4.0.1

v4.0.1 — see RELEASE_NOTES_v4.0.1.md

v4.0.0

Catalyst UI v4.0.0 — formerly Claude Code Studio

Released: 2026-05-28 (testing repo)
Theme: Rebrand + Hugging Face Hub integration

---

What this release is

v4.0.0 is the Catalyst UI release. The app you've been using as
"Claude Code Studio" since v1 is now called Catalyst UI —
reflecting the broader scope: a single desktop workbench for Claude,
Hugging Face, Ollama, Aider, Gemini, and OpenRouter, with every panel
built around the same terminal-first workflow.

Nothing was removed. The Claude Code CLI is still the centrepiece;
your settings, snippets, GitHub PAT, model registry, LMM journal, cost
history, and theme all carry forward automatically. See
docs/MIGRATING_FROM_CCS.md for the full walk-through.

---

Headline: Hugging Face panel

A new sidebar panel (smiley glyph) opens the Hugging Face Hub:

Browse

• Search the 1M+ Hub models live (text query + optional task filter).
• GGUF only checkbox on by default — surfaces models you can run
  locally via Ollama.
• Result cards show downloads, likes, pipeline tag, tags, license,
  gated status.
• Expand a card → loads the full model info + GGUF variants with
  quant tags (Q4_K_M, Q8_0, F16, etc.) and file sizes.
• Import to Ollama button on every GGUF variant — synthesises a
  catalog entry (hf.<repo>.<quant>) and spawns
  ollama run hf.co/<repo>:<quant> via the shared MODELS_LAUNCH
  pipeline. Entry persists in the Models panel under Local with a
  "HF Import" badge.
• Fallback Copy ollama cmd button for users who want to paste
  the command elsewhere.

Cached

• Lists the resolved cache directory (prefers ~/.cache/huggingface/hub
  if you already have one, falls back to <userData>/hf-cache).
• Per-repo size + Remove button.
• Refresh.

Research

• Disabled by default. Behind an explicit opt-in disclaimer
  (community-curated uncensored / experimental catalogs).
• Once enabled, same search surface as Browse but seeded with
  research-leaning queries (uncensored, etc.); Import button uses
  research:true which adds a "Research" badge + a
  hf-research.<repo>.<quant> prefix so you can tell them apart in
  Models.
• Audit log panel (collapsible, persistent at
  <userData>/huggingface-research-audit.jsonl) records every
  research launch (timestamp / repoId / quant). Clear button.

---

Resizable right panel

The right-side panel was a fixed 320 px wide. v4.0.0 bumps it to a
default 420 px (HF + Models both want more room as cards get
richer) and adds a 4 px drag handle on the left edge.

• Drag to resize between 280 and 800.
• Choice persists in localStorage.
• Double-click the handle resets to default.

Implemented as a generic PanelResizeHandle so future layouts can
reuse it.

---

The rebrand (what changes, what doesn't)

Identity changes

Surface	Before	After
Product name	Claude Code Studio	Catalyst UI
Installer artifact	Claude-Code-Studio-...	Catalyst-UI-...
TitleBar	Claude Code Studio	Catalyst UI (fka Claude Code Studio)
StatusBar	Claude Code Studio vX.Y.Z	Catalyst UI vX.Y.Z
Popout title	<label> — Claude Code Studio	<label> — Catalyst UI
Start-menu shortcut	Claude Code Studio	Catalyst UI
Tray tooltip	Claude Code Studio	Catalyst UI
Onboarding modal	Welcome to Claude Code Studio	Welcome to Catalyst UI
Settings copy	references "Claude Code Studio"	references "Catalyst UI"
package.json name	claude-code-studio	catalyst-ui
GitHub repo	LxveAce/claude-code-studio	LxveAce/catalyst-ui
Testing repo	claude-code-studio-testing	catalyst-ui-testing

Preserved (so your install upgrades in place)

• Windows appId stays com.lxveace.claude-code-studio — NSIS
  uses appId to decide upgrade-vs-parallel-install; we want upgrade.
• userData directory still
  %APPDATA%/Claude Code Studio (Windows),
  ~/Library/Application Support/Claude Code Studio (macOS),
  ~/.config/Claude Code Studio (Linux). Anchored via
  app.setPath() on whenReady. Nothing in your state directory
  moves or gets renamed.

---

Auto-update path

Users on v3.2.1 will see v4.0.0 via the in-app updater (Settings →
Updates → Check for updates). The v3.2.1 update fix (Item 2 of the
v3.2.1 polish pass) is exactly what makes this work — latest.yml
now ships with every release.

GitHub maintains permanent redirects from the old repo URL to the new
one, so v3.2.1 binaries' baked-in LxveAce/claude-code-studio updater
endpoint continues to resolve after the lockstep repo rename.

---

Verification

• npx tsc --noEmit clean
• npm run vite:build clean
• All 8 Phase B PRs merged and verified individually on testing-master:

PR	Title
#38	feat(hf): @huggingface/hub backend service + IPC + types
#39	feat(hf): HFPanel UI — Browse / Cached / Research sub-tabs
#40	feat(hf): GGUF → Ollama bridge (Import button + shared launcher)
#41	feat(hf): Research catalogs + audit log + research-mode imports
#42	feat(layout): resizable right panel + 420 default + persist width
#43	chore(rename): Catalyst UI (formerly Claude Code Studio)
#44	release(v4.0.0): bump version + CHANGELOG + release notes

---

What's next

• docs/MIGRATING_FROM_CCS.md — what carries over and what's new.
• Issue tracker moves to the new repo: https://github.com/LxveAce/catalyst-ui/issues.

v3.2.1

Claude Code Studio v3.2.1

Released: 2026-05-28 (testing repo)
Theme: Polish pass — 8 user-reported bugs + the new Accessibility section

---

Headline

This is a polish release driven by user-reported issues in the live
v3.2.0 build. No new headline features; everything here either fixes
something that didn't work, makes something easier to use, or surfaces
a workflow that was hidden. A new top-level Accessibility section
joins Settings, with ten persisted toggles.

Full plan + per-item file paths in
docs/PLAN_2026-05-28_10-items.md.

---

Fixed

"Get a key →" link works for every provider

The OpenAI / Gemini / OpenRouter / Anthropic key portal links inside
the ApiKeyModal were silently blocked by the openExternal IPC
allowlist (which only knew about model registries). Hosts are now
listed explicitly; blocked URLs log a console warning so the next
omission is loud instead of silent.

Auto-updater no longer 404s with a stack trace

Two-part fix. In the main process, UpdaterService.on('error') now
detects HttpError 404 on latest*.yml specifically and demotes it
to a one-line console warn with no UI state. In CI, the release
workflow now uploads dist/latest.yml (Windows), dist/latest-mac.yml
(macOS), and dist/latest-linux.yml (Linux AppImage) alongside the
installers — those were excluded back in v2.0 and never re-added, so
every v3.x release shipped without the auto-updater manifest.

API Models tab shows all providers

The persisted catalog on upgraded installs only kept entries
present at first install. SEED_VERSION bumped 2 → 3 so the
existing seed-merge migration runs on next launch, pulling in
Claude Chat / Gemini / Aider / OpenRouter and the new
GPT-4o-mini entry for users whose registry is stuck on a
smaller set. Also renamed Aider (multi-provider) →
OpenAI GPT-4o (via Aider) and added a new force-refresh
mechanism for display-only fields so renames propagate to
existing users without overwriting their customisations.

Copy command actually copies

handleCopyCommand previously called navigator.clipboard.writeText
async-without-await and swallowed any rejection. New
IPC.APP_CLIPBOARD_WRITE uses Electron's main-process clipboard
(reliable regardless of focus state); the renderer falls back to
navigator.clipboard for dev mode, then alert() with the command
line if both fail. Successful copy flashes the button green
"✓ Copied!" for 2 seconds.

Search bar is usable

Previously 140px wide, font-size 11, padding 4×8 — and hidden on the
API tab. Now 280px+ wide, font-size 13, padding 8×12, with a
matching radius and visible on both Local and API tabs. Tier / role
filters stay gated to Local (they don't apply to API entries).
A new models.focus-search hotkey (default Ctrl+F) opens the
Models panel and focuses + selects the search input from anywhere.

LMM panel focus-aware, "+ New cycle" actually opens

• Both LMMPanel and CompactPanel now accept an activeFamily
  prop (derived from the focused terminal tab). Non-Claude
  families get a dashed "switch to a Claude tab" hint, and LMM's
  + New cycle button is disabled for them. Both panels
  refresh() whenever the active family changes.
• + New cycle no longer uses window.prompt() — replaced with
  an in-app modal (input + Create/Cancel, Enter submits, Esc
  cancels, errors surface via the existing ErrorBanner).

Pop-out + chat-skin sync

• MODELS_POPOUT IPC now takes a 3rd profile arg, URL-encoded
  into the popout window. App.tsx parses ?profile= and
  threads it to PopoutView → EmbeddedTerminal →
  ChatSkinOverlay. Chat-mode profiles keep their stream-json
  renderer in popouts instead of falling back to the TUI
  sanitizer.
• [paneId not found] no longer cold-flashes on popouts that
  just hadn't seen listRunning settle. Probe at 1.5s, retry at
  +2.5s if empty, only declare the PTY dead after the second
  negative. Cleanup cancels pending probes on unmount.
• Chat-skin toggle syncs across windows for the same paneId via
  the localStorage storage event.

"+" button opens the profile picker

The "+" tooltip claimed Ctrl+Shift+T for years even though no
binding existed and the button hard-coded a new Claude tab. Now
+ opens the same ProfilePicker that the ▼ arrow opens; the
picker's search input handles Enter on empty query as
"pick Claude" so Ctrl+Shift+T → Enter still creates a Claude
tab in one hand-off. New terminal.new-profile hotkey wired
with Ctrl+Shift+T as its real default.

---

Added

Accessibility section under Settings

Brand-new section with ten persisted toggles:

1. High contrast — WCAG-AAA palette override (overrides theme)
2. Font size — 90 / 100 / 115 / 130 % multiplier
3. Reduce motion — disables animations + transitions
4. Large focus ring — 3px gold outline on focused elements
5. Large click targets — 44px min-height (WCAG-AAA touch spec)
6. Dyslexia font — OpenDyslexic stack with Comic Sans fallback
7. Screen reader mode — data-attr hook; aria-live wiring in follow-up
8. Keyboard hints overlay — floating list of active hotkeys
9. Color-blind palette — SVG color-matrix filters
   (protanopia / deuteranopia / tritanopia)
10. Audio captions — placeholder for v4.0.0 HF audio integration

Persisted at <userData>/accessibility.json via the atomic
tmp+rename pattern shared with cli-flags / compact-controller.
Renderer applies prefs to document.documentElement on
hydration + on every change, so toggles take effect without a
reload. Defaults: everything OFF — no behavior change for
existing users until they opt in.

---

Catalog changes

• New entry OpenAI GPT-4o-mini (via Aider) for cost-sensitive
  iterative runs through the same Aider CLI as GPT-4o.
• Rename: api.aider.multi → display name OpenAI GPT-4o (via Aider)
  (force-refreshed on existing installs via the new
  FORCE_REFRESH_DISPLAY_IDS migration).

---

Verification

• npx tsc --noEmit clean.
• npm run vite:build clean.
• node scripts/runtime-verify.mjs — runs against the previously
  shipped assertions; visual-only Accessibility toggles will be
  added to the verifier in a follow-up PR.
• Manual smoke against the 8 user-reported issues across the
  shipped UI.

---

Pull requests in this release

PR	Title
#28	docs(plan): two-phase delivery for 10-item ideas list
#29	fix(ipc): allow PROVIDER_KEY_URL hosts in openExternal allowlist
#30	fix(updater): demote missing-latest.yml 404 + restore CI yml uploads
#31	feat(models): API tab providers + OpenAI clarity + Copy command toast
#32	feat(models): larger search bar, on both tabs, Ctrl+F to focus
#33	feat(lmm,compact): focus-aware panels + in-app New Cycle modal
#34	fix(popout): thread profile, soft retry, sync chat-skin toggle
#35	feat(tabs): + opens profile picker + Ctrl+Shift+T hotkey
#36	feat(a11y): Accessibility section under Settings with 10 features

v3.2.0

Claude Code Studio v3.2.0

Released: 2026-05-27 (testing repo)
Theme: Tab-based terminal + structured chat-mode

---

Headline features

Terminal Tabs (replaces split-pane layout)

A Windows-Terminal-style tab strip is now the primary terminal UX.
The previous split-pane layout from v3.x is gone.

• + button → new Claude tab.
• ▼ profile picker → catalog dropdown grouped API / Local. Pick any
  model (Claude, Ollama, Aider, Gemini, BitNet) → spawns its CLI in
  a new tab.
• Tab strip: status dot · label · ↗ popout · × close per tab.
• Tabs can be popped out into separate windows (PTY stays alive in
  the main window's tab).
• Session schema bumped v1 → v2. Existing sessions migrate cleanly
  on first launch — the first pane from your old layout becomes a
  single Claude tab on the same paneId so any alive PTY reattaches.
• Renderer-side cap at 32 tabs (matches main-side MAX_TABS).
  Past the cap, a dismissable yellow notice tells you to close a
  tab first.

Claude (Chat) profile — structured JSON conversation

New catalog entry that runs the Claude CLI in non-interactive
bidirectional JSONL mode (--print --input-format=stream-json --output-format=stream-json --verbose). Pairs with the ✦ Chat
overlay to produce a real chat UI — no more TUI repaint sequences
getting garbled into the chat skin.

• Pick Claude (Chat) from the ▼ picker (now appears alongside
  the bundled Claude entry).
• Toggle ✦ Chat skin → structured rendering of all Claude event
  types: text bubbles, tool_use cards, tool_result cards, thinking
  blocks.
• Tool cards show a #abc123 correlation badge that matches across
  paired tool_use ↔ tool_result calls.
• Stop button replaces the Send button while a response streams —
  sends SIGINT to halt generation.
• New capability probe: on app launch we run claude --help and
  badge the Claude (Chat) entry with a yellow "CLI flags?" pill
  if your local Claude binary doesn't appear to support stream-json.

Commands sidebar mirrors the active tab

The Commands panel (Quick Actions / All Commands / Shortcuts) now
follows the active terminal tab's CLI. Six command families
curated: Claude / Ollama / Aider / Gemini / BitNet / Terminal-unknown.

• Header chip ("CLAUDE", "OLLAMA", "AIDER", …) announces which CLI
  the panel is showing commands for.
• Quick Actions with trailing-space "starter" commands (Aider
  /add , /drop , etc.; Ollama /set system ) now land in the
  composer without auto-submitting an empty argument; the active
  terminal auto-focuses so you can finish typing.
• Click any command → routes to the active tab's PTY via the same
  sender registry that snippets and the palette use.

Runtime verifier upgraded

node scripts/runtime-verify.mjs now runs 30 assertions instead
of 12:

• 12 sidebar panel renders (boot + each panel switch, no console
  errors).
• 18 extended assertions covering tab add/close, profile picker
  open + Esc-close, Commands family chip text, Ctrl+Shift+P palette
  open + Esc-close.

Used as the smoke gate for every PR in this release.

---

Smaller wins

• Model tab PID footer: StatusBar PID readout now works for
  model tabs (it harvests the pid from models.listRunning() on
  attach). Previously showed 0.
• EmbeddedTerminal registerSender wired through, so palette /
  snippet text injection actually reaches model PTYs.
• CLI onboarding routes /login to a Claude tab when the active
  tab is a non-Claude model (otherwise it'd type /login into
  ollama / aider and confuse).
• Echo dedup in the chat-mode renderer uses whitespace-normalized
  comparison, so Claude's internal text normalization doesn't cause
  user messages to render twice.
• Tool-input summary field-priority list expanded to 18
  candidates (catches Anthropic SDK conventions: target_file,
  cmd, q, instruction, etc.).
• Tool-result image hints show media_type + source kind +
  approximate size: [image: image/png, base64, ~24 KB] instead of
  bare [image].

---

What's NOT in this release (deferred)

Two Mediums explicitly classified as cosmetic by their original
red-teams:

• closeTab focus fallback uses a closure-captured tabs array
  (narrow timing window; persistence layer corrects).
• Commands panel content swaps instantly on tab switch (no fade
  animation).

Various Lows tracked per-review remain deferred per category L
policy.

---

Verification

• npx tsc --noEmit clean.
• npx vite build clean.
• node scripts/runtime-verify.mjs 30/30 passing.
• 5 separate security reviews (docs/security-reviews/) with all
  H+M findings closed in-release.
• Visual smoke against a real Claude binary is recommended for
  the chat-mode + tool-use + Stop button paths — the verifier
  exercises the renderer but doesn't drive Claude itself.

---

Upgrade notes

• Session file migration is automatic. v1 sessions become a single
  Claude tab on the first pane's id.
• Settings unaffected. Themes, hotkeys, snippets, GitHub PAT, etc.
  all persist across the upgrade.
• Local model tabs are session-ephemeral by design — only Claude
  tabs persist across restart. Open your Ollama / Aider models again
  from the picker after upgrade.

---

Pull requests in this release

10 stacked PRs merged together (#18–#27 on the testing repo):

PR	Title
#18	feat(tabs): wire TerminalTabs into App + session schema v2
#19	feat(commands): mirror active tab profile + register EmbeddedTerminal sender
#20	feat(chat-mode): Claude --stream-json profile + JSONL parser
#21	chore(polish): submit flag for starter commands + MAX_TABS cap
#22	feat(chat-mode): render tool_use / tool_result / thinking blocks
#23	fix(embed): surface model PTY pid for StatusBar
#24	feat(chat-mode): Stop button replaces Send while streaming
#25	feat(cli): claude --help capability probe + picker badge
#26	chore(tool-use): pairing badge + richer summary fields + image hint
#27	chore(polish): capNotice + auto-focus + dedup + onboarding routing

v3.0.0

Claude Code Studio v3.0.0

The multi-model release. Three months of work landing in one push: a
33-model curated catalog of local + API models with hardware-aware
recommendations, a file directory navigator, accurate per-bucket
resource monitoring, a --dangerously-skip-permissions toggle, an
in-app Danger Zone for Reset / Uninstall, and a long list of red-team
fixes from beta testing.

Cross-platform: Windows (NSIS), macOS (DMG), and Linux (AppImage,
.deb, .rpm) all built from the same source.

Download

OS	File	Notes
Windows	Claude-Code-Studio-3.0.0-Windows.exe	One-click NSIS installer. Bundles Node + Claude CLI.
macOS (Apple Silicon)	Claude-Code-Studio-3.0.0-Mac.dmg	Drag to Applications. First launch bootstraps Node + Claude CLI.
Linux Universal	Claude-Code-Studio-3.0.0-Linux-Universal.AppImage	Portable single-file build. Works on any distro.
Linux Debian / Ubuntu	Claude-Code-Studio-3.0.0-Linux-Debian.deb	sudo apt install ./Claude-Code-Studio-3.0.0-Linux-Debian.deb
Linux Fedora / RHEL	Claude-Code-Studio-3.0.0-Linux-Fedora.rpm	sudo dnf install ./Claude-Code-Studio-3.0.0-Linux-Fedora.rpm

What's new in v3.0.0

Multi-model catalog

• 33 curated local + API models (Qwen, DeepSeek, Llama, Gemma, Granite, Phi, Mistral, embeddings) — see docs/MULTI_MODEL.md for the full list and selection criteria.
• Hardware-aware recommendations — auto-detects your tier (toaster / low / mid / high / workstation) based on RAM + VRAM and surfaces the right defaults.
• Project-aware suggestions — scans your cwd for package.json, pyproject.toml, Cargo.toml, etc. and weights recommendations by detected role (frontend / backend / data / systems / mobile / devops).
• In-panel terminal viewer — see the launched model's PTY output without leaving the Models tab.
• Pop-out windows — separate BrowserWindow per model for side-by-side workflows.
• First-run picker — auto-opens after install with top 3 recommendations for your hardware; pre-pulls them via Ollama.
• Disk-quota check — warns before pulling if free disk space is less than 1.5× the model size.
• License disclosure — restricted-license models (Llama, Gemma, BigCode) prompt before launch.
• Add custom model — form to register your own model with the catalog.

File directory navigator (new sidebar panel)

• Lazy-loaded tree, one folder level per IPC call. Opening a project with node_modules doesn't freeze the renderer.
• Recent projects list, persists across launches.
• Show / hide dotfiles toggle.

Resource monitoring rebuilt

• Three separate buckets: Claude PTYs, model PTYs, Ollama daemon. Pre-v3 the "Claude" gauge silently aggregated everything spawned via PtyRegistry — accurate numbers only when you weren't running local models.
• O(n) process-tree walk (was O(n²)) — handles big multi-model setups smoothly.
• Ollama daemon detection via process-name scan — picks up the persistent daemon + its model-loader children even when no model PTYs are spawned by Studio.

Cost accuracy

• Rates updated to current Anthropic pricing (Haiku $1/$5, Sonnet $3/$15, Opus $15/$75 per 1M tokens). Verified against anthropic.com/pricing.
• Local models are free + not counted — disclaimer made explicit.

GitHub error handling

• 401 / 403 / 404 / network errors get one-line actionable messages instead of raw stack traces. Rate-limit errors include the reset time when present.

Settings additions

• --dangerously-skip-permissions toggle in Claude CLI section. When on, the Claude CLI launches with permission prompts bypassed automatically. Applies only to Claude PTYs, never to local models.
• Danger Zone with two buttons:
  • Reset user data — wipes 18 known JSON / JSONL files (settings, history, model registry, debug logs); leaves Chromium profile state intact.
  • Uninstall Claude Code Studio — Windows spawns the NSIS uninstaller; macOS opens Finder at /Applications with drag-to-Trash instructions; Linux detects install format and surfaces the right apt / dnf / rm command.
• Status bar shows current git branch + dirty indicator. Polls every 30s + on window focus.
• Single source of truth for version — title bar, status bar, and About row all read from app.getVersion(). Pre-v3 each was hardcoded and drifted (the v2 build shipped with v1.0.0 in the title bar).

Sign-in flow

• Sign In button now sends /login (Claude's in-session slash command) instead of claude login (which the running Claude session interpreted as chat text). Caught during beta testing.

NSIS installer (Windows)

• Ollama is no longer bundled in the installer. Beta.1 silently downloaded + installed Ollama (~2 GB) during install with no progress UI; users reasonably thought it was stuck. v3 detects Ollama at runtime instead and offers a one-click install link via the FirstRunPicker.
• Uninstaller prompts to also remove the user-data JSON files (defaults to No so a planned reinstall keeps settings).

Auto-updater

• Skips beta builds entirely so beta testers don't get a 404 stack trace from electron-updater looking for latest.yml on a release that doesn't have one. Stable v3.0.0 builds auto-update normally.

Upgrading

From v1.0.0 — uninstall via Windows Settings → Apps first. v1 used Squirrel; v3 uses NSIS. The two installers don't know about each other.

From v2.0.0 — Windows: uninstall via Settings → Apps (the v3 installer's "remove userData?" prompt will offer to preserve your settings). macOS/Linux: drag to Trash / apt remove and reinstall.

From v3.0.0-beta.x — same uninstall-and-reinstall pattern. Settings are forward-compatible.

Known limitations

• Per-provider API keys (OpenAI, Gemini, OpenRouter) — only Anthropic auth is wired. Other API models in the catalog need manual claude-style env-var setup.
• Model comparison view (run same prompt against multiple models) — not built. Workaround: use pop-out windows.
• Embedding-RAG over past sessions — catalog includes embedding models (Qwen3 Embedding, BGE-M3) but the indexing pipeline isn't built.
• VRAM per loaded model — Resource panel shows RAM by bucket but not VRAM per model (requires vendor GPU SDKs).
• macOS code signing — unsigned build. First launch may show "App is damaged" — right-click → Open → Open. To fix permanently, set up Apple Developer Program ($99/yr) + osxSign config.

Credits

Multi-model catalog research compiled May 2026 against:

• Ollama Library, Hugging Face GGUF index
• LMSYS Chatbot Arena, HumanEval / MBPP, MMLU-Pro, EvalPlus, BigCodeBench leaderboards
• Independent reviews: InsiderLLM 2026, RTX 5070 benchmarks (Pooya Golchian), index.dev reviews

Built with Electron 42, React 19, Vite, node-pty, xterm.js, Octokit.

v2.0.0

Claude Code Studio v2.0.0 — Release Notes (Draft)

Template — fill in the verification checkmarks and bump
package.json to 2.0.0 (drop the -dev.1 suffix) before publishing.

Headline: v2.0 ships on Windows, macOS, and Linux with a one-click
bootstrap installer that sets up Node + the Claude CLI for you. No more
manual npm install -g step on any platform.

---

What's new in v2.0

Cross-platform support

OS	Installer	Bootstrap timing
Windows	NSIS Setup.exe (one-click silent install)	At install time via the installer
macOS Intel	DMG drag-to-Applications (x64)	At first launch via the onboarding modal
macOS Apple Silicon	DMG drag-to-Applications (arm64)	At first launch
Linux Debian / Ubuntu	.deb package via dpkg -i	At first launch
Linux Fedora / RHEL	.rpm package via rpm -i or dnf	At first launch
Linux any distro	AppImage (portable single file)	At first launch

Same Node 22.22.3 runtime and same @anthropic-ai/claude-code CLI on
every platform. Same SHA256-pinned downloads, same registry pinning,
same security posture.

First-launch onboarding (all platforms)

The onboarding modal — which already shipped in v1.1 on Windows — now
works on macOS and Linux too. It:

1. Detects if claude is installed and authenticated via claude doctor.
2. If missing: "Install Claude CLI" button downloads Node + Claude CLI
   into <userData>/runtime/ with live streaming progress.
3. If unauthenticated: "Sign in to Claude" types claude login into
   the embedded terminal so the CLI can open your browser for OAuth.
4. "Don't show again" persists the choice. Settings → Claude CLI →
   "Re-show CLI onboarding" undoes it.

Auto-updates everywhere via electron-updater

Replaced v1.0's Squirrel-only update-electron-app with
electron-updater. Update flow now works on Windows (NSIS), macOS
(DMG + zip), and Linux AppImage uniformly. deb/rpm rely on the distro
package manager (apt upgrade / dnf upgrade).

Other carryovers from v1.1 (not yet released as v1.x)

• Esc-to-close on the onboarding modal.
• Live npm install log streaming in the modal (no more "Installing… (?)"
  silence).
• Download progress indicator in the StatusBar while updates download.
• Re-show CLI onboarding from Settings → Claude CLI.

---

Upgrading from v1.0

Windows v1.0 users must uninstall the Squirrel install before
installing v2.0 — see
docs/MIGRATING_FROM_V1.md. Your settings
in %AppData%\Claude Code Studio\ are preserved automatically.

macOS and Linux users are new to Studio in v2.0 — no migration
needed.

---

Per-platform "first install" warnings

Windows SmartScreen

The installer isn't yet code-signed (tracked for v2.1). On first run
Windows shows "Windows protected your PC". Click More info →
Run anyway. Appears once per machine.

macOS Gatekeeper

The app isn't yet notarized (tracked for v2.1). On first launch
macOS may say "Claude Code Studio cannot be opened because the
developer cannot be verified." Right-click the app → Open →
confirm in the dialog. Required once.

Linux

No equivalent warning. chmod +x the AppImage if downloaded; deb/rpm
install via your normal package manager.

---

Known issues

• Code-signing deferred to v2.1. Apple Developer Program ($99/yr) +
  Sectigo OV Windows cert (~$70/yr) — both tracked.
• Linux update channels: AppImage gets electron-updater. deb/rpm
  rely on your distro's package manager; no in-app update prompt.
  Future v2.x may add a custom repo at packagecloud.io or similar.
• macOS bootstrap requires tar on PATH. Always present on macOS.
• Linux bootstrap requires tar with xz support. xz-utils is
  standard on Ubuntu 20.04+, Fedora 30+, etc. On minimal images,
  install via apt install xz-utils or dnf install xz.
• Bootstrap requires internet during first launch. The CLI is
  ~30 MB + Node is ~30 MB. Online-only; no offline variant yet (BACKLOG
  Phase 4b — ship if any user reports install failure).
• Beta channel is settings-only until the publisher pipeline splits
  prerelease routes (BACKLOG C3).

---

For developers

The hybrid build pipeline carries forge for dev / Squirrel-format builds
and electron-builder for the v2.0 multi-OS installers. See
CONTRIBUTING.md:

• npm start — forge dev (unchanged)
• npm run dist / dist:mac / dist:linux — electron-builder
• npm run dist:all — Windows + Linux on a Linux build host (mac needs
  a Mac)

GitHub Actions CI (.github/workflows/ci.yml) builds all 3 OSes on
every push via the matrix job. Artifact downloads available for 30
days per run.

Windows local builds need Developer Mode enabled
(see CONTRIBUTING.md).

---

Maintainer verification checklist

Before publishing v2.0.0:

Windows

• CI's build-installer (windows-latest) job green, OR
  npm run dist succeeds locally with Developer Mode on.
• Downloaded Setup.exe; ran on a clean Windows machine (or after
  uninstalling v1.0). Bootstrap completes, app launches, onboarding +
  sign-in work.

macOS

• CI's build-installer (macos-latest) job green for both x64 and
  arm64 DMGs.
• Downloaded DMG; dragged to Applications; ran with right-click →
  Open (Gatekeeper bypass). First-launch onboarding downloads Node +
  CLI; sign-in works.

Linux

• CI's build-installer (ubuntu-latest) job green. AppImage + .deb
  • .rpm all produced.
• AppImage: chmod +x + run from terminal. First-launch onboarding
  works.
• .deb: sudo dpkg -i succeeds on Ubuntu 22.04 LTS. App appears in
  applications menu, first launch works.
• .rpm: sudo rpm -i succeeds on Fedora 39+. Same first-launch
  validation.

Update path

• After v2.0.0 tag, bumped to v2.0.1 and published. v2.0.0 install
  receives the update via electron-updater (Windows + macOS + Linux
  AppImage). deb/rpm tested with manual package upgrade.

Publishing v2.0.0

The repo ships a tag-driven release workflow at
.github/workflows/release.yml. To publish:

1. Bump package.json version → 2.0.0.
2. Commit, then:

   git tag v2.0.0
   git push origin v2.0.0

3. The release workflow auto-triggers and runs in parallel on
   windows-latest + macos-latest + ubuntu-latest. Each runs the
   appropriate npm run dist:publish:* script with the
   auto-provided GITHUB_TOKEN, which lets electron-builder create
   (or update) a draft release tagged v2.0.0 with all per-OS
   artifacts:
   • Claude.Code.Studio-2.0.0-Setup.exe + latest.yml
   • Claude.Code.Studio-2.0.0-x64.dmg, ...-arm64.dmg, +
     latest-mac.yml
   • Claude.Code.Studio-2.0.0-x64.AppImage +
     claude-code-studio_2.0.0_amd64.deb +
     claude-code-studio-2.0.0.x86_64.rpm + latest-linux.yml
4. Once V1-V4 above pass on the draft release, edit the GitHub
   release → uncheck Set as a pre-release if checked → Publish
   release. electron-updater's latest*.yml feed picks it up
   immediately for existing installs.

Verifying auto-update post-publish

After the v2.0.0 release is published (not just drafted), confirm
auto-update by:

1. Install v2.0.0 from the published release.
2. Bump package.json to 2.0.1, commit:

   git tag v2.0.1 && git push origin v2.0.1

   The release workflow publishes v2.0.1 as a draft.
3. Promote v2.0.1 from draft → published on GitHub. This is the
   critical step — drafts are invisible to electron-updater. The
   feed at https://github.com/LxveAce/claude-code-studio/releases/latest/download/latest.yml
   (or latest-mac.yml / latest-linux.yml) needs to point at the
   newer release.
4. Open the running v2.0.0 install. Within ~5 minutes (the
   update-electron-app default check interval — applies the same
   for electron-updater), the StatusBar shows
   "Downloading update… X%" then "Update v2.0.1 ready".
5. Close and reopen the app. v2.0.1 is now running.

If step 4 doesn't fire, hit Settings → Updates → Check now
(rate-limited to once per 5s) to force a poll.

Per-platform caveats:

• Linux deb / rpm installs don't auto-update — that's a property
  of those formats, not a bug. Users update via
  sudo apt upgrade claude-code-studio (deb) or
  sudo dnf update claude-code-studio (rpm) after the publisher
  pipeline ships to those repos (not v2.0 — future work).
• Linux AppImage does auto-update via electron-updater. The
  current AppImage gets replaced in-place when the user accepts the
  restart prompt.
• macOS updates via the .zip artifact (electron-updater
  applies the zip onto the running app bundle). DMG is just the
  install-time delivery format.
• Windows updates via Squirrel-Windows-style delta or full from
  the NSIS Setup.exe.

---

Credits

• Phase 4-9 (Windows bootstrap installer) shipped on
  feature/bootstrap-installer — 15 commits, 10 per-phase red-team
  reviews under docs/security-reviews/.
• v2.0 multi-OS work shipped on feature/macos-support (acted as the
  multi-OS branch since macOS + Linux share the same cross-platform
  code path).
• Friend's prior PRs (anjaustin/*) all merged into master before this
  effort started.
• LMM thinking discipline + per-phase red-team applied throughout.
  Per-source-file analyses under journal/.

v1.0.0

v1.0.0 — first packaged release

All seven plan phases shipped (Phase 4 GitHub + 4.5 LMM + 5 Auth +
6 Vault Sync + 7a Palette/Snippets/Notifications + 7b Auto-updater +
7c Split panes + 7d Tray/Hotkeys + 7e Cost tracker + 7f Conversations).

Installer artifacts at out/make/squirrel.windows/x64/:
- Claude Code Studio-1.0.0 Setup.exe (175 MB)
- claude_code_studio-1.0.0-full.nupkg (174 MB)
- RELEASES (Squirrel update manifest)

Build requires Node 22 LTS (Node 24 incompatibility documented in
HANDOFF.md). Renderer / asar / node-pty native unpacking all
verified in this build per SECURITY_REVIEW_PACKAGING.md.