Terminal-first workspace manager for AI coding sessions on macOS.
WorkSpaces gives you a native app that wraps a terminal with some niceties for spinning up isolated workspaces. Designed to optimize terminal-based coding agent workflows.
- Any terminal agent: Embedded terminal with workspace management around it. Anything that runs in a shell works — Claude Code, Aider, Codex CLI, or a plain
bashsession. - Fork-friendly: No backwards-compatibility baggage. Take what works, change what doesn't.
- Opinionated defaults: Three-column layout, terminal-first workflow, lifecycle hooks. Customizable by editing the source directly.
Download Latest Release (macOS 14.0+)
- macOS 14.0 (Sonoma) or later
- Apple Silicon or Intel Mac
- Download the latest
.dmgfrom Releases - Open the DMG and drag WorkSpaces to Applications
- Launch from Applications (first time: right-click > Open)
- Three-column layout: sidebar, terminal, and detail pane
- Restores the last active repo overview, workspace terminal, or web view on launch
- Repository overview with workspace and web-view creation
- Nested repo-scoped web views and workspaces in a single calm source list
- Repository sorting with stable
AlphabeticalandLast Accessedmodes - Persistent terminal sessions for repo and workspace rows
- Integrated GhosttyKit terminal surface
- Two-pane split controls driven by Ghostty actions (
Cmd+D, focus, resize, equalize) - Embedded web views with global, repo-owned, and workspace-owned scope
- File browser and git status view
cmd+oto open repo in editor, defaulting to zed- Lifecycle hooks (
scripts/setup,scripts/stop,scripts/archive; legacysetup.sh/archive.sh)
- Launch app and resume your last repo overview, workspace terminal, or web view
- Add repositories manually if needed
- Click a repo row to open its overview, or expand it to jump into web views and workspaces
- Create workspaces or add web views from repo actions
- Click a workspace row to open its terminal context
- Use the right pane for files and git changes
swift run workspaces
swift run workspaces .
swift run workspaces repo add ~/code/my-repo
swift run workspaces ws new my-repo feature-auth
swift run workspaces open my-repo/feature-auth --cmd "claude"
swift run workspaces ws race my-repo "add a health endpoint" --n 3 --cmd "claude"
swift run workspaces ws launch my-repo/feature-auth --cmd "claude" --json
swift run workspaces ws read my-repo/feature-auth --lines 50
swift run workspaces ws send my-repo/feature-auth --text "run the tests" --enterws race fans one prompt across N fresh worktree workspaces (race-<slug>-1..N)
and runs the agent headlessly in each (<cmd> -p '<prompt>', output in the
workspace's .race-agent.log). Use workspaces open <repo>/<name> to attach to
any of them interactively.
ws launch is the detached counterpart to open: it returns a handle instead of
attaching, so a script can start an agent and come back to it. The handle is a
tmux session on the app's own -L workspaces socket, named the way the app names
that workspace's terminal — opening the workspace in the app (tmux-per-session
mode) attaches to the agent already running there rather than starting a second
one. --name <label> launches a sibling session instead. ws read and ws send
take either a handle or a workspace selector.
Open Settings (Cmd+,) to configure workspace root location.
WorkSpaces is designed to be forked. There's no plugin system or extension API — instead, the codebase itself is the API. Common customizations:
- Change the layout: Edit
ContentView.swiftto rearrange panes - Add lifecycle hooks: Drop project lifecycle scripts into
scripts/(setup,stop,archive) or use legacy root hooks (setup.sh,archive.sh) - Customize repo overview and sidebar behavior: Start with
RepoLandingView.swift,SidebarView.swift, andSidebarRows.swift - Swap the terminal: The
TerminalViewwrapper abstracts the terminal backend - Adjust keyboard shortcuts: See
ShortcutRoutingPolicy.swift
If you build something interesting on top of this, open an issue.
backlog/ROADMAP.md and the other files in backlog/ sketch a loose direction. It evolves as the project gets used and developed — nothing there is a promise.
Bootstrap a fresh checkout with:
./scripts/setupAfter bootstrap, use the root mise catalog for day-to-day work:
mise run build-ghosttykit
mise run build
mise run test
mise run check
mise run dev-launch
mise run dev-smoke
mise run evidence -- --pr <number> --name <slug>Lume validation entry points are also available from the root catalog:
mise run dev-lume-ensure
mise run dev-lume-preflight
mise run dev-lume-standalone-validate
mise run dev-lume-macos-smokeRun mise tasks for the full top-level catalog. Web dashboard tasks stay in web/.mise.toml; run them with mise -C web run <task>.
The bootstrap path validates and trusts only the reviewed root/web mise configs, then installs locked tool versions. Keep secrets and broad trust settings out of mise config; see mise security.
For a product-level overview of WorkSpaces, see:
For contribution guidelines and project structure, see:
For release/signing/notarization details, see:
For performance testing and benchmarking workflows, see:
For introducing Settings-gated UI experiments, see:
For local app-shell automation from WorkSpaces terminal tiles, see:
For VM and provider-backed workspace architecture, see:
- docs/vm-provider-architecture.md
- docs/development/lume-integration.md
- docs/development/lume-validation.md
- docs/development/lume-recreate-runbook.md
- docs/development/evidence.md
The Lume validation flow uses isolated WorkSpaces-managed VM storage and a standalone validated-base manifest before the app will reuse a macOS base VM.
For the Agent Factory (autonomous pipeline) system overview and trust model, browser-openable directly, see:
For UI smoke/capture script entry points, see:
Apache-2.0 — Copyright 2026 Michael Fairchild