Claudesk
CLAUDE.md11 starsChanged 2 days agoMITView on GitHub
Claudesk — a macOS-only, single-user, open-source "lite IDE" that puts the daily Claude Code + Sublime Text workflow in one window with multiple virtual workspaces inside it. The pain point: starting work on any given project takes minutes of repetitive setup (open terminal → cd → claude, open Sublime Text and load project, open Sublime Merge and load again, occasionally a second terminal and cd again). Over 20+ rotating projects with 3–4 in flight on any given day, this cost…
- Installs packages
In this repository2 other files it gives its agents.
- clear-build-cacheSkill
- releaseSkill
The file
Files
Claudesk
Project Overview
Claudesk — a macOS-only, single-user, open-source "lite IDE" that puts the daily Claude Code + Sublime Text workflow in one window with multiple virtual workspaces inside it. The pain point: starting work on any given project takes minutes of repetitive setup (open terminal → cd → claude, open Sublime Text and load project, open Sublime Merge and load again, occasionally a second terminal and cd again). Over 20+ rotating projects with 3–4 in flight on any given day, this cost compounds. Compounding it: when several projects ARE in flight, finding the one waiting on input means clicking through windows or switching Spaces — a second-order tax on top of the launch tax.
Claudesk provides:
- VSCode-style project picker — click a project → full environment fires up in <10s. Each pick opens a new workspace inside the existing Claudesk window (a new tab/stage), not a new OS window.
- One workspace = one project = one CC session. Single window holds N workspaces concurrently.
- Mission Control-inspired layout. Center stage = the focused workspace, full-size; top filmstrip = live thumbnails (or status tiles, pending the Phase 1 thumbnail-rendering probe) of every other open workspace, ordered, with project name + idle/running/awaiting-input dot. Clicking a filmstrip tile promotes that workspace to center stage and demotes the previous one. Filmstrip is collapsible to a row of mini status tiles (project name + status dot only) for reclaiming vertical space.
- Left half of each workspace: Claude Code in a true PTY-backed terminal, yolo mode by default, already
cd'd into the project. Rendered with xterm.js DOM renderer (no WebGL). - Right half of each workspace: a placeholder in Phase 1; a built-in lite editor + git diff viewer arrives in Phase 3.
- Stateful CC controller (Phase 2): Claudesk owns each workspace's CC process lifecycle, watches workflow state files, and exposes workflow operations (skill buttons, Recycle Session) as clicks rather than typed slash commands.
- Menu-bar status item (Phase 2): an aggregate idle/running/awaiting-input dot in the macOS menu bar — click to open a popover listing every workspace + status; clicking a row brings Claudesk forward and switches the center stage. Always visible system-wide, even when the Claudesk window is hidden, minimized, or on a different Space.
- Picture-in-picture mini player (Phase 2, conditional): a small always-on-top floating panel (via
tauri-nspanel) the user can summon when the Claudesk window is out of focus. Mirrors the same status surface as the filmstrip. Display-only in v1 — clicking a tile does NOT bring the workspace forward. Conditional on Phase 2 dogfooding: if the menu-bar item alone suffices, PiP may defer to Phase 4. - Smart auto-resume on workspace open (M12 — ✅ SHIPPED 2026-08-05): opening a project fires the right resumption command by itself and announces it before you click. ⚠️ TWO signals, not three: unclean-exit flag → spawn with the
--continueCLI flag; else.session.mdpresent → inject/session-restore; else nothing (/session-startis never auto-fired — it gets an explicit button). ⚠️ The unclean flag BEATS.session.md. ⚠️/session-resumeand/session-pauseDO NOT EXIST — renamed/session-restore//session-handoffat M9 WP5. The refuted three-branch design + precedence proof:arch/session-resumption.md→ "The two signals". - Drive-mode selector on the PICKER ROW (M12; ⚠️ NOT the workspace header): a compact readout, click to edit, showing the project's drive mode (1
stepping/ 2orchestrated/ 3autopilot/ 4fsd— ⚠️ notstep-by-step/full-autopilot, which no workflow skill recognizes; authority is upstreamtransitions.md). ⚠️ As built it IS a native<select>— reversing the "never a live<select>on every row" rule, because the four values are a closed set and a bad mode string fails serde on read and takes the whole project list down. The model override's open-string rule must NOT be generalized here. Seearch/session-resumption.md→ "The picker-row cell". - Sublime launchers (both KEPT permanently — revised 2026-06-20, WP8): Sublime Text and Sublime Merge are each one click away via icon buttons in the right-panel tab row. ⚠️ The Sublime Text pop is NOT removed — the in-app editor is the primary editing surface, but Sublime Text stays as a permanent escape hatch. See "Key Decisions" below.
Audience — two tiers (stance refined 2026-07-20; supersedes the earlier flat "no design concession for users who don't share the workflow"): (1) the workflow-independent lite-IDE core — picker, workspaces, PTY terminal, editor/diff, hook-driven status surfaces, time analytics — which any Claude Code user gets out of the box; and (2) an opt-in, default-OFF workflow-orchestration layer (M10.9's workflow_features_enabled gate) for users who install the companion workflow system at ~/.claude/skills/. The primary user is a single operator (Stayman) running that system against 20+ rotating projects on macOS. The refinement is not a softening: with the gate OFF the app is byte-identical to one that never had the workflow features, so a secondary user meets no dead affordances rather than a diluted tool. See workflow-system/product/vision.md §Target Audience + roadmap M10.9.
Full vision, roadmap, research, architecture, and WBS live in workflow-system/product/.
External reference
The companion workflow-system project (my-claude-code-customization) is symlinked at _ref/claude-customization/ (gitignored). It's the source of truth for the workflow skills, orchestrator agents, and transitions.md that Claudesk integrates with. Read from it when you need current skill or transition definitions. Notable paths:
_ref/claude-customization/workflow-system/product/transitions.md— pause-policy tables and drive-mode definitions_ref/claude-customization/agents/<workflow>-workflow/AGENTS.md— orchestrator procedures_ref/claude-customization/skills/— skill bodies (installed copies live at~/.claude/skills/)
Tech Stack
- Tauri 2 (2.9.x line) — Rust desktop framework with native WKWebView on macOS; ~3MB bundle, ~30–40MB RAM idle. Single
WebviewWindowhosts all workspaces (no multi-webview). - Rust (stable, ≥1.77) — backend: process lifecycle, PTY, filesystem, external-tool launch (Sublime via
sublime_open), project config persistence. Phase 2 also: Unix-socket hook listener + status broadcaster. - TypeScript + React 19 + Vite — frontend. WorkspaceList in React state; all workspaces stay mounted, switching center stage is
display: nonetoggling. - xterm.js (
@xterm/xterm+@xterm/addon-fit) — terminal renderer. DOM renderer only — no@xterm/addon-webgl. Research established that WebGL contexts cap at ~16 per browser page; with a multi-workspace tab shell, the DOM renderer is simpler and good enough for the foreground. tauri-plugin-pty(wrapsportable-pty) — embedded PTY in the Rust core (NOT node-pty + sidecar).- In-app Sublime-pop hotkey — a webview
⌘⇧Ekeydownhandler owned by the focused workspace (WP8). NOT an OS-global shortcut: notauri-plugin-global-shortcut, no macOS Accessibility permission. (The OS-global approach was built then rejected at verify-human 2026-06-19 — see WP8 inworkflow-system/product/archive/phase-1-bare-shell-poc/wbs.md.) tauri-plugin-fs/tauri-plugin-dialog— file IO, file dialogs. (The Sublime launch usesstd::process::Commanddirectly, nottauri-plugin-shell.)- Phase 2 additions:
tauri-nspanelv2.1 (PiP NSPanel),tauri-plugin-positionerwithtray-iconfeature (menu-bar popover positioning),tauri-plugin-fs-watch/notify(workflow-system/state/.session.mdfile-watcher). - No database — project list is a flat JSON file at
~/Library/Application Support/com.claudesk.app/projects.json(app_data_dir()resolves to the bundle identifiercom.claudesk.app, not the productName). - No backend infrastructure — single-user desktop app.
Project Structure
⚠️ Strategic docs + workflow state live under one workflow-system/ root (migrated 2026-07-28, aacc687); docs/ holds only lessons/ + demo/. A pre-migration reference to docs/product/* or a top-level workflow/ is stale — see the tree below for the live layout.
claudesk/
├── CLAUDE.md # this file
├── CHANGELOG.md # append-only narrative log
├── README.md # + docs/demo/*.gif embeds (M8)
├── runtimes.md # per-project runtime registry (long-command timeouts)
├── _ref/ # gitignored — symlinks to companion repos for read-only reference
├── docs/
│ ├── lessons/ # extracted topic docs — verify-self tiers, MCP-bridge caveats,
│ │ # sandboxed-$HOME, PiP main-thread rule
│ ├── reference/ # reference material
│ └── demo/ # filmstrip.gif, pip.gif (M8 demo assets)
├── workflow-system/
│ ├── product/ # vision, roadmap, arch, wbs, design-priors, context
│ │ ├── m11-wbs-parked.md # M11's decomposition, parked while M10.9 runs
│ │ └── archive/ # <cycle-name>/ per closed milestone (11 so far)
│ ├── outbox/ # HANDOFF-to-mccc-*.md — Claudesk-side copies of messages SENT to
│ │ # other workspaces (mirror of their inbox/); cited by bare filename
│ └── state/
│ ├── wip/ # active feature/task/incident items
│ ├── backlog.md # SURFACE discoveries (+ backlog-quality-findings.md)
│ ├── archive/ # completed items
│ └── .session.md # transient session pointer (gitignored)
├── src/ # frontend (React 19 + TS)
│ ├── components/
│ │ ├── workspace/ # Workspace, RightPanelHost, Filmstrip, editor/,
│ │ │ # diff/, filetree/, search/, dashboard/, finder/
│ │ └── picker/ # ProjectPicker (+ today's ad-hoc settings strip)
│ ├── state/ # WorkspaceList store, fsChange, appView
│ ├── pip/ # PiP NSPanel webview entry
│ ├── updater/ # in-app updater UI (M10)
│ ├── menu/ # menuBridge (native menu → webview)
│ └── probe/ # dev-only harnesses (not shippable UI)
├── src-tauri/ # Rust backend (~20 modules)
│ ├── src/
│ │ ├── cc_session/ # CcSession trait + PtyCcSession impl
│ │ ├── config_store/ # projects.json + settings.json persistence
│ │ ├── status_broadcaster/# hook events → workspace-status fan-out
│ │ ├── hook_socket/ # AF_UNIX listener; hook_install/ registers in ~/.claude
│ │ ├── time_store/ # time-analytics SQLite (write-gated) + reclassify/
│ │ ├── editor_fs/ fs_index/ fs_watch/ git_diff/ git_status/
│ │ ├── pip/ tray/ app_menu/ updater/ env_path/ sublime/ finder/
│ │ └── lib.rs, main.rs
│ ├── Cargo.toml
│ ├── tauri.conf.json # + tauri.dev.json (dev-identity overlay)
│ └── capabilities/
├── tooling/demo/ # dev-only demo-GIF pipeline (M8)
├── tmp/scratch/ # gitignored throwaway vitest specs (NOT the CC scratch workspaces:
│ # those live OUTSIDE the repo in ../claudesk-scratch/)
├── package.json
├── pnpm-lock.yaml
└── tsconfig.jsonDev Environment
Rationale for host-based dev env (copied from arch.md): This is a desktop application targeting macOS. Tauri development requires direct access to the host's WKWebView, macOS code-signing chain (for later phases), and native windowing — all of which a Docker container on macOS cannot provide. The standard Tauri 2 toolchain runs natively on macOS via rustup + node. Industry practice for Tauri development is host-based; Dockerizing it would add friction without benefit.
Commands run directly on the host. Standard setup and tooling apply.
Getting Started
Prerequisites
- macOS (this project is macOS-only and will not be tested on Linux or Windows)
- Rust (stable, ≥1.77) via
rustup - Node 20 LTS or newer (recommend
fnmornvm) - pnpm (preferred) —
npm i -g pnpmor viacorepack enable - Xcode Command Line Tools —
xcode-select --install - Sublime Text with
sublonPATH(or fallback toopen -a "Sublime Text") - Sublime Merge with
smergeonPATH— Phase 2 only - Claude Code CLI (
claude) installed and authenticated independently before launching Claudesk - (No macOS Accessibility permission needed — the Sublime launchers are in-app buttons, not OS-global shortcuts.)
Setup
From a fresh checkout:
pnpm install
pnpm tauri:dev # dev build — runs under the com.claudesk.app.dev identity (isolated from a prod install)To build a production .app:
pnpm tauri buildDev/prod isolation (2026-06-24): pnpm tauri:dev launches with --config src-tauri/tauri.dev.json, which overlays a distinct bundle identifier com.claudesk.app.dev (productName "Claudesk Dev", window title "Claudesk (dev)"). This isolates the dev build's app-data dir, projects.json, hook socket, deployed hook script (claudesk-hook-dev.pl), and ~/.claude/settings.json registration from a production install (com.claudesk.app) — so the installed .app and pnpm tauri:dev can run concurrently with no cross-talk (required for dogfooding Claudesk with Claudesk). The hook-script basename + registration marker derive from the running app's identifier at runtime (single source of truth — hook_install::commands::script_basename); a dev build's projects.json seeds once from the prod list on first launch. Plain pnpm tauri dev (no overlay) would collide with a prod install — use pnpm tauri:dev.
Development Conventions
- Workflow system. This project follows the workflow system documented in
~/.claude/CLAUDE.md(Product → Feature/Task/Incident state machines). Use/session-startfor end-to-end orchestration; entry-point slash commands (/feature-plan,/feature-spec,/task-plan,/incident-report) for single-step work. - WIP layout. Active features in
workflow-system/state/wip/<feature>.mdusing the Work Tree format (see~/.claude/CLAUDE.md→ "Work Tree Format"). Discoveries logged inworkflow-system/state/backlog.md. Completed items archived toworkflow-system/state/archive/. - CHANGELOG.md. Append-only narrative —
**Feature shipped:** …,**Task closed:** …,**Backlog resolved:** …, etc. Closing skills write to it automatically. - Code style.
- ⚠️
pnpm verify:autoIS the per-phase verify-auto gate — run that one command, not a remembered list. Order:lint→format:check→tsc --noEmit→check:link(rollup; the only step that sees a deleted export at runtime) →vitest→cargo fmt --check→cargo clippy --all-targets -D warnings→cargo test. ⚠️cargo fmt --checkand--all-targetsare in there deliberately (never--lib, which skips the test target). Why each step earns its place — no CI/no git hook, the Prettier reflow that broke a?rawguard, thecargo fmtgap found at paydown WP1:docs/lessons/verify-auto-gate.md. - Frontend: ESLint + Prettier. TypeScript strict mode on. React 19 function components only.
- Backend: no
unwrap()outside of tests; use?with typed error returns (thiserror).
- ⚠️
- Dark mode only. Claudesk's UI is always dark — it never follows the OS theme. Do NOT add
@media (prefers-color-scheme: light)blocks or any light-theme tokens.:rootinsrc/App.csssetscolor-scheme: darkand unconditionally dark color tokens; keep it that way. A light/theme toggle is explicitly out of scope (not even a Phase 4 setting). - Tests.
- Backend:
cargo testfor unit tests; integration tests insrc-tauri/tests/. - Frontend: Vitest for unit tests; component tests where state logic is non-trivial.
- End-to-end: deferred; manual testing on the host macOS is the verification path in Phase 1.
- ⚠️ Read the four verification lessons below before verifying anything non-trivial — they are the single biggest source of defects here, and each one exists because a green result was wrong.
- Installed-build smoke test (dev-vs-installed parity) · scratch workspaces (
../claudesk-scratch/scratch-{a,b,c}, OUTSIDE the repo, mandatory once a check spawns/answers a CC session) · ⚠️ extracting a pure state machine proves the MACHINE, not its CALLER (hit twice in M11 WP4, one a shipped CRITICAL — funnel shared-state writes through ONE function and guard that). ⚠️ Anything touching PATH, env vars, or external-process spawning MUST be smoke-tested from an installed.applaunched from Finder/Dock;pnpm tauri:devinherits the terminal's env and will not reproduce GUI-PATH failures. →docs/lessons/verify-self-tiers.md - ⚠️ Live verify-self via the
tauriMCP bridge — prefer it over carrying visual/DOM checks to the operator, but read the caveats first: several have produced false verdicts, including (h) a freshly-opened CC pane reading blank, (i) the xterm DOM not being the buffer, and (l)__TAURI_INTERNALS__having noinvokeproperty to patch. ⚠️ Instrument agreement is not correctness when both share a defect, and never conclude "no IPC happened" from a JS-level tap without a positive control. →docs/lessons/mcp-tauri-bridge-caveats.md - ⚠️ Guards that report green while checking nothing — 19 numbered ways a guard stops checking, the comment-budget rule, and THE render-harness authority (jsdom render + live
act/createRootmounts work today with no new dependency; render a DOM question, guard only a source question). Ask before trusting any guard: could this pass if the code it names were deleted? and which steps can actually APPEAR in what I am asserting over? ⚠️ Mutation-prove each form INDIVIDUALLY. →docs/lessons/source-text-guards.md - Sandboxed-
$HOMElaunch — verifying a~/-touching feature without touching the operator's real home. ⚠️ TheRUSTUP_HOME/CARGO_HOME/PATHoverrides are mandatory, not optional. →docs/lessons/sandboxed-home-verification.md
- Backend:
- One window, many workspaces. Claudesk is single-window; N projects = N workspaces inside it, switched via filmstrip tiles. ⚠️ Multi-window for Claudesk itself is explicitly out of scope. The only auxiliary surfaces are the PiP NSPanel (M5) and the menu-bar popover (M6). Popped Sublime windows are external apps, not Claudesk windows, so they don't violate this (see the Sublime launcher decision below).
- Tab-shell substrate ships in Phase 1. Even though Phase 1 only ever opens one workspace at a time, the WorkspaceList + Center Stage + (empty) Filmstrip layout is built from day one. Phase 2 plugs into the existing structure rather than reshaping it. Design for N=1 with N>1 in mind.
- All workspaces stay mounted. Switching the center stage is
display: none/display: blocktoggling, never an unmount/remount. PTY connections persist across switches; CC sessions in background workspaces continue to receive output (buffered to xterm scrollback). - xterm.js DOM renderer only. Do not load
@xterm/addon-webgl. The WebGL renderer caps at ~16 contexts per page across all xterm instances on the page combined; with a multi-workspace tab shell that's a real ceiling, and the modern DOM renderer is fast enough for the foreground workspace. If a single-workspace user ever proves the DOM renderer can't keep up, the decision is reversible (one-line addon load) — but never load it speculatively. - Single
WebviewWindow, no multi-webview. Tauri 2's multi-webview API isunstable-flagged and offers webview isolation we don't need (all workspaces share Claudesk's trust boundary). All workspaces are React components in one webview. - No
.claudesk.jsonper repo. Project list is centralized at~/Library/Application Support/com.claudesk.app/projects.json(the bundle-identifier pathapp_data_dir()returns). Adding or removing a project is a UI action, not a per-repo file edit. CcSessiontrait is a stable seam. Claudesk's "how to drive CC" path goes throughCcSession. Phase 1 hasPtyCcSession; never bypass the trait when calling CC from anywhere else. Phase 2 extends the trait withstate_events()andrecycle(); future work could swap to anSdkCcSession.- PTY byte-injection for input; hook channel for state. ⚠️ NEVER from PTY output. We write bytes into the CC pty to send a slash command, but we do not parse CC's output text to infer state: workflow state comes from
workflow-system/state/.session.mdvia a file watcher, and CC's idle/running/awaiting-input state from its official hook channel over a Unix socket. ⚠️PostToolUseis the answer-resume signal (answering a prompt fires it, NOTUserPromptSubmit), andNotification→AwaitingInput is gated onnotification_typebackend-side instatus_broadcaster::event_to_state. ⚠️ An UNLISTEDnotification_typefalls back to AwaitingInput — right for input-needed types, WRONG for completion ones; classify each new one deliberately (M13.5 WP2:agent_completedfell through and lit the dot blue;SubagentStopwas never involved). ⚠️ FOUR states, not three —Stopwith outstanding background work →BackgroundWork(purple). The hook forwards the count + each task'stype, never command/description. ⚠️ Amonitor-onlyStop(an artifact watch) is Idle (M16.5 WP4; exclude that one type, never allow-list; the count decides when the types are absent or misaligned). ⚠️ Every verify-human pause reads BLUE via a gated display overlay (attention), not a fifth state. Display surfaces read it throughdisplay_state/displayStateFor; the close/quit and respawn guards readstate. Full event table, 5-type vocabulary, socket path:workflow-system/product/arch/status-channel-and-surfaces.md. - CC hook channel uses Unix socket, not shared file. Resolved by research: with three concurrent status-surface consumers (filmstrip, menu-bar, PiP), Unix-socket multi-consumer concurrency wins decisively. Claudesk opens the socket on launch; the installed CC hook script writes one JSON line per event.
- Status broadcaster fans out one stream to three subscribers. Filmstrip (main webview), menu-bar popover (separate webview), and PiP (NSPanel webview) all subscribe to the same Tauri-event-channel broadcast of
WorkspaceStatusUpdate. All three surfaces agree at all times. - ⚠️ PiP/NSPanel window ops MUST run on the main thread. Any background-thread/timer path calling a PiP window op must marshal via
app.run_on_main_thread(…). Off-main-thread AppKit ops abort the process with a native exception and NO Rust panic — invisible tocargo test, presenting as clean-launch-then-silently-die. ⚠️#[command]fns +on_window_eventare main-thread — which cuts BOTH ways: an AppKit call inside one is safe, but athread::sleep/blocking poll, or a lock held across a main-thread-marshaling call, freezes the UI. A synccc_killdoing exactly this hung the app (P1 2026-08-25;samplewas the instrument that found it). Blocking work belongs on a worker (SessionRegistry::take+thread::spawn), or in anasynccommand viaspawn_blocking. ⚠️ Enforced since paydown WP9 bysrc-tauri/tests/sync_commands_do_not_block.rs(transitive,syn-based, fails on the pre-fixcc_kill; itsLEDGERholds the accepted exceptions). It does NOT see a lock held across a marshal, and it does not scanasynccommand bodies: each async command is listed in itsASYNC_COMMANDStable with a reason, and a(async)sync body with an unbounded wait holds a runtime worker (the dry run did, fixed at paydown 2026-11-04 WP4). Seedocs/lessons/pip-nspanel-main-thread.md. - ⚠️ Drive mode: Claudesk NEVER writes the WIP file's frontmatter — REVERSED 2026-08-06 (M12 WP4; the WIP-frontmatter mirror was rejected). As built: stored per-project in
projects.json(default_drive_mode), delivered as an env-var-gatedUserPromptSubmithookadditionalContextline. ⚠️ The "companion skills unchanged" half is REVERSED (2026-11-02, M16.5 WP5 5.8): the skills read the line for the mode but stopped SKIPPING the menu, so mccc was asked for an explicit skip-when-present rule (+ a point-and-select picker); the hook sentence stays fact-only. Claudesk reads the workflow's world; it does not write it. Why the mirror could not work + the full pipeline:arch/session-resumption.md→ "The drive-mode signal". - Pre-risky-action checklist for scaffolders. Scaffolders (
create-tauri-app,npm create *, etc.) can wipe strategic docs. Before running one in a non-empty dir, ensure git is clean and scaffold into a sibling dir then merging. The strategic docs inworkflow-system/product/, the rootCLAUDE.md, and the_ref/symlink are load-bearing and must survive any scaffold.
Setup & Ecosystem Gotchas
Setup-time pitfalls discovered during WP1 that any fresh checkout will hit.
- pnpm v11+ moved
onlyBuiltDependencies. The allowlist for postinstall scripts now lives inpnpm-workspace.yamlasallowBuilds:, NOT inpackage.json'spnpm.onlyBuiltDependenciesfield. On first install, pnpm v11 auto-generates a stubpnpm-workspace.yamlcontaining the literal textset this to true or falseas a placeholder — that string must be replaced withtrue(orfalse) beforepnpm installwill succeed. Current state:esbuild: trueinpnpm-workspace.yaml. - ESLint pinned to v9 LTS. ESLint v10 (Nov 2025) is incompatible with
eslint-plugin-react7.37.x — the plugin usescontextOrFilename.getFilenamewhich v10's API removed (TypeError: contextOrFilename.getFilename is not a functionon every lint run).eslintand@eslint/jsare pinned to^9untileslint-plugin-reactships a v10-compatible release. Do not bump to v10 without first verifying the plugin has caught up. - Prettier ignores strategic docs by design.
.prettierignorelistsdocs/,workflow-system/(wasworkflow/before the 2026-07-28 layout migration — the pattern was updated with it, so the unified root stays protected),CLAUDE.md, andruntimes.md— these are hand-authored prose where Prettier's blank-line-before-bullet-list rewrites are unwanted. Do NOT remove those entries casually; if you need to run Prettier on a sub-tree of those dirs, do it with explicit paths rather than removing the ignore rule.pnpm formatskips them silently by design. - A dependency spike must live OUTSIDE the repo tree —
tmp/being gitignored does NOT isolate a pnpm install. Runningpnpm addinside the repo's gitignoredtmp/still rewrites the trackedpnpm-lock.yaml: pnpm resolves upward to the workspace root and does not honor gitignore for that resolution (the tell is../..in its progress output).package.jsonis left untouched, so the usual "did I add a dep?" check — greppingpackage.json— reports clean while the lockfile is dirty. Put library bake-offs / "just try it in a sandbox dir" spikes in the session scratchpad (outside the repo) instead, and when verifying a no-footprint claim checkpnpm-lock.yamlexplicitly, not justpackage.json. Hit 2026-08-01 (M11 WP1) while spiking two markdown renderers; caught bygit statusbefore any commit and reverted. Not to be confused with[[pnpm-exec-shadows-local-binaries]], which is aboutpnpm exec <bin>silently shadowing a local binary. - GUI-launched app inherits a minimal PATH (install-only). A Finder/Dock-launched macOS
.appinherits the minimal launchdPATH(/usr/bin:/bin:/usr/sbin:/sbin), NOT the user's shellPATH— so user-installed CLIs (claudein~/.local/bin, Homebrew/fnm/nvmbins) are invisible to spawned processes andcc_spawnfails with "No viable candidates found in PATH …". This bites only the installed build —pnpm tauri:devinherits the launching terminal's fullPATH, so it never reproduces (operator hit it 2026-06-24 on first real install). Fixed app-wide bysrc-tauri/src/env_path/: at.setup()(FIRST, before any spawn) the app captures the login-shellPATH($SHELL -l -i -c 'printf %s "$PATH"', fallback/bin/zsh) andstd::env::set_var("PATH", …)process-wide — best-effort, never blanks an existingPATH. If you add another external-CLI spawn, it benefits automatically; do NOT re-introduce per-spawn PATH hacks.
Current Milestone
⭐ ACTIVE: M17 — Remote workspaces (one SSH host first) (planned 2026-11-14). A workspace whose CC runs on another Mac (first: the tank-sim-lite-demo Mac mini) over SSH + tmux, with session-level parity. The IDE half is absent on it (vision Core Principle 7). The tank-sim-lite-demo project's checkpoint is 2026-12-11.
- Scope + lifecycle rulings R-1–R-4 (explicit close/quit = end; a passive drop = keep running and reconnect; Detach / Reconnect; unclear → dialog):
roadmap.md→ "### Milestone 17". - Design (⚠️ PLANNED, not as-built):
workflow-system/product/arch/remote-workspaces.md. Evidence (live-probed):research.md. WPs + sizing:wbs.md(WP1 probe ∥ WP2 rows first; ⭐ a partial-release point after WP6). - ⚠️ Data-loss trap:
prune_missing_projectsdeletes any row whose path doesn't exist locally. A remote row needs the exemption (WP2.2) before any build writes one to the realprojects.json.
Direction (vision revisit, 2026-11-14): Claudesk is a cockpit for parallel CC sessions. A workspace = one CC session in a context (local dir, profile, remote host), and the IDE half attaches where a local tree exists. Prior: a-workspace-is-its-cc-session. ✅ M16.5 closed 2026-11-08. The latest release is git tag --sort=-v:refname | head -1.
⚠️ Closed cycles' "do NOT re-derive" rulings are EXTRACTED, not dropped. Read the matching file before touching that subsystem:
- Workflow supervisor (M15 + M16.5): as-built
workflow-system/product/arch/workflow-supervisor.md. The M15 rulings R-1–R-4, the two refuted premises (message.modeldoes not give the context window; there is no skill registry), the mccc ownership boundary ("absorb the machine, not the skills") and every M16.5 WP verdict →docs/lessons/closed-cycles-m14-m16-5.md. ⚠️ The supervisor is headless and owns NO guard arm: the OFF-invariant pin stays at 6 arms / 10 subjects. - Media viewer (M16):
arch/right-panel-surfaces.md→ "Media in the editor tab" andarch/security-posture.md→ "Media transport"; its rulings (the 4 GiB cap, no newTabKind, the%PDF-gate, frame-midpoint seeks) → the same lesson. - M14 remainder (R-1 signing reverses M10, minisign stays; R-2 settings = hotkeys only): the same lesson.
- M13 / M13.5:
docs/lessons/closed-cycles-m13-m13-5.md.
⚠️ A deleted ES-module export is a RUNTIME failure, not just a tsc error — never split an export deletion from its consumer migration across phases; boot-smoke-test before trusting any live observation on a phase that deleted anything (full write-up: the high-priority entry in backlog.md).
⚠️ A release is a VERIFICATION prerequisite, not just distribution — an installed-.app check cannot pass until a release containing the feature is installed. ⚠️ Silence from a component whose success is invisible is NOT evidence it works: find a positive observable before resolving on "no complaints".
Previous Milestone (closed)
⚠️ As-built architecture is organized BY SUBSYSTEM, not by milestone — workflow-system/product/arch/<subsystem>.md, indexed by arch.md (split 2026-08-12). A milestone's WBS + probe outcomes live in workflow-system/product/archive/<cycle-name>/. Where the arch/ set and roadmap.md differ, the arch/ set is the authority — it is the as-built record, resynced at each /product-finalize. ⚠️ Do not add a new milestone section to it; edit the subsystem the change belongs to.
M1–M12 all closed GO (M1 2026-06-19 → M12 2026-08-12; 15 cycles counting the M10.5/M10.9/M11.5 inserts). ⚠️ Do not maintain a milestone→as-built table here — it duplicated roadmap.md (which carries each milestone's close note) and the arch.md index (which maps every subsystem to its file), so it was a third copy drifting against two authorities. Look up a closed milestone's as-built home in arch.md's index; its WBS + probe outcomes are in workflow-system/product/archive/<cycle-name>/.
Releases via the /release skill. ⚠️ Do NOT record the latest version here — this line went two releases stale once, then went stale again. git tag --sort=-v:refname | head -1 is the authority; main runs ahead of the last tag by design. Trust anchor unchanged since v0.2.9 (key 774E2E8429FDF78A), so existing installs self-update; CHANGELOG carries each release's contents.
Key Decisions
- Tauri 2 over Electron. Aligned with the "lite over featureful" principle. Bundle ~3MB vs ~96MB; ~30–40MB RAM vs ~200–300MB idle; startup <500ms vs 1–2s. The smaller ecosystem maturity is acceptable for a single-user tool.
tauri-plugin-pty/portable-ptyover node-pty + sidecar. node-pty would require shipping a Node runtime in the bundle, defeating the bundle-size advantage. portable-pty runs natively in the Rust core.- PTY byte-injection over Agent SDK for v1. The vision requires the familiar interactive CC TUI inside the workspace. Claudesk is the terminal, so injecting bytes for slash commands is legitimate; we avoid the "PTY scraping" anti-pattern (parsing output text for state) by using the hook channel + file-watching for state detection in Phase 2. The
CcSessiontrait is the future-swap seam for Agent SDK if/when needed. - Single window, many workspaces (replaces "one project per window"). Reversed during the 2026-06-15 product revision. Multiple projects = workspaces inside one Claudesk window, switched via filmstrip tiles. Aligned with the revised vision.
- xterm.js DOM renderer only — no WebGL. Decided 2026-06-15 after research established the ~16-context browser cap. DOM renderer is simpler, sufficient for the foreground, and removes a swap-on-focus complexity. Decision is reversible if needed.
- Single
WebviewWindow, no multi-webview. Tauri 2's multi-webview isunstableand offers no isolation we need. - Tab-shell substrate ships in Phase 1. Phase 2 plugs into existing layout structure rather than reshaping the foundation.
- Thumbnail-rendering probe (WP4) gates Phase 2's filmstrip + PiP rendering strategy. Pass → live ~1 fps mirrors. Fail → static status tiles in v1, live mirrors deferred to Future Possibility.
- CC hook channel uses Unix socket, not shared file. Three concurrent status-surface consumers make the multi-consumer concurrency case unambiguous.
- Flat JSON for the project list, no DB. ≤100 entries; read-on-open, write-on-update; JSON is appropriate.
- No per-project config file in the project itself. Centralized list in app support dir aligns with the "no per-project config burden" principle.
- Host-based dev environment, not Docker. Tauri targets host WKWebView and native windowing; Docker on macOS cannot provide them.
--dangerously-skip-permissions(yolo) by default. Vision-explicit. Phase 4 setting will let users opt out.- Sublime launchers are click-only icon buttons in the panel tab row (WP8, redefined 2026-06-20). Both Sublime Text (
sublime_open) and Sublime Merge (smerge_open) launch from icon buttons in theRightPanelHostright-panel-toggletab row (sublime/sublimeLaunch.ts); the backendsublimemodule is unchanged. ⚠️ NO OS-global shortcut and no macOS Accessibility permission — that approach was built and rejected. ⚠️⌘⇧Owas freed when the in-app hotkey was deleted as redundant with the button — and F-a WP3 CLAIMED it (2026-09-22) for the Prompt panel, so it is no longer free; seesrc/components/workspace/panelHost.ts. Both launchers are PERMANENT — the in-app editor is the primary surface, but Sublime Text stays as a one-click escape hatch alongside Sublime Merge (staging/blame/history/blob-at-rev the inline diff viewer doesn't cover). Seeworkflow-system/product/vision.mdCore Principle 3. - Phases 2–4 not decomposed yet. Phase 1 decomposition is full; Phases 2–4 are WP-headline only. Premature decomposition would force decisions about later-phase internals before Phase 1 surfaces real constraints.
- PiP click-to-focus is a Future Possibility, not v1. Display-only PiP first; promote-on-click deferred until dogfooding confirms the limitation is real.
- Workflow state-machine enforcement & claude-time integration are future possibilities, NOT in the initial roadmap. Architecturally we leave room for them (see
workflow-system/product/vision.md→ "Future Possibilities") but don't build toward them in Phases 1–4.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

