ccws

claude code · workspace manager

The workspace layer
for Claude Code.

Bind scattered directories into a single folder. Open it in Claude Code and the whole project is in scope — no flags, no --add-dir rituals, no JSON by hand.

curl -fsSL https://raw.githubusercontent.com/edditz/ccws/main/scripts/install.sh | sh -s -- --repo edditz/ccws

single-file binary · macOS / Linux / WSL · no Node required

01

What's a workspace?

A workspace is just an empty folder. ccws drops a .claude/settings.json into it that points at the real directories you care about, via permissions.additionalDirectories.

Launch Claude Code inside that folder and every linked directory joins the session. Move a file from ~/projects/web into ~/projects/api; both are in scope. ccws is the wiring — you never touch the JSON.

  • No registry. Workspaces are plain folders under ~/.ccws/; discovery is a directory scan.
  • Absolute paths only. Stored normalized, deduped, validated. add fails atomically if any path is missing.
  • Field-safe. Your other settings.json keys are preserved on every write; corrupt JSON is never overwritten.
~/.ccws/my-work/
├─ .claude/
│  └─ settings.json
│     └─ permissions
│        └─ additionalDirectories
│           ├─ /Users/you/projects/web
│           ├─ /Users/you/projects/api
│           ├─ /Users/you/notes/research
│           └─ /Users/you/labs/exp
└─ open claude here → everything above is in scope
02

Six commands.

~/my-work
$ ccws init my-work
✓ created workspace "my-work" at ~/.ccws/my-work
$ ccws add ~/projects/web ~/projects/api -w my-work
✓ added 2 directories to "my-work"
$ ccws list
my-work…………2 dir(s)
research………1 dir(s)
$ ccws status
workspace: my-work (~/.ccws/my-work)
  ✓  /Users/you/projects/web
  ✓  /Users/you/projects/api
$ ccws open my-work
entering workspace… claude launched in ~/.ccws/my-work
$ ccws remove ~/projects/web -w my-work
✓ removed 1 directory from "my-work"
03

Get ccws.

One-line install

Detects your platform, verifies the SHA-256 checksum, installs to ~/.local/bin.

curl -fsSL https://raw.githubusercontent.com/edditz/ccws/main/scripts/install.sh | sh

Manual binary

Grab ccws-<os>-<arch> from the latest release, chmod +x, put it on your PATH.

releases / latest →

From source

bun install then bun run build. Or run it straight from source with bun run src/cli.ts <cmd>.

view source →

targets · darwin arm64 · x64  |  linux x64 · arm64  |  windows x64