Concepts

Isolated workspaces

How Kalauz seals each unit of work in its own git worktree and branch.

A workspace is a fresh branch plus its own git worktree. Because every workspace has a separate working directory, agents can't overwrite each other's files, and you can run as many as your machine will carry.

Why worktrees

A single checkout forces agents to take turns: one edit, one set of files on disk. Git worktrees give every branch its own directory backed by the same object store, so Kalauz keeps many branches checked out at once — cheaply, and without re-cloning. No stashing, no merge collisions between agents.

How a workspace maps to git

When you create a workspace, Kalauz runs the equivalent of:

git worktree add -b kalauz/<slug> <worktree-path> HEAD
  • Branch — kalauz/<slug>, where the slug comes from the workspace name. If that branch already exists, Kalauz retries with a timestamp suffix.
  • Worktree path — under the active profile's worktrees root, organized by repository, e.g. ~/.kalauz/worktrees/<repo>/<slug> — outside the main repo so it never disturbs your primary checkout.
  • Identity — your git user.name / user.email are applied to the worktree's local config, respecting the active profile.

Environment files

Secrets and local config usually live in files git ignores, so they wouldn't exist in a fresh worktree. Kalauz copies files matching the project's Files to copy patterns — .env* by default — from the repo into the new worktree before the setup script runs, so your scripts have what they need.

What stays isolated

  • The working directory and any uncommitted changes.
  • Build artifacts and dependency installs scoped to the worktree.
  • The agent's process — it only ever sees its own workspace.

Shared git history is the one thing every workspace has in common. Commits made in one workspace are visible to others only after they land on a shared branch.

Turning worktrees off

Worktrees are on by default. You can disable them under Settings → Git, or force them off with the KALAUZ_NO_WORKTREE=1 environment variable (which also locks the setting). With worktrees off, workspaces operate directly on the project's current branch and share state — useful for repos where worktrees aren't practical.

Cleanup

Archiving a workspace marks it IsArchived and folds it into the Archived section of the sidebar; the worktree stays on disk so you can revisit it. An optional archive script runs in the worktree first.

What's next?