How-to Guides

Claude Code git worktree workflow

Run Claude Code in Kalauz by opening a workspace for each task. Each workspace is an isolated git worktree with its own branch, so Claude can edit, test, commit, and be reviewed without touching your main checkout or another agent's files.

Kalauz keeps the workflow close to the command line you already use: it launches the claude CLI from your PATH, applies the active profile's credentials and git identity, and shows the resulting diff in place.

1. Connect Claude Code

Install Claude Code and make sure claude is available on your PATH. Kalauz does not ask for a separate Claude login; it drives the existing CLI and reuses the session it already holds.

Open Configure model providers to confirm Claude is connected. If the CLI is missing, Kalauz reports CLI not found until claude can be resolved or a managed executable path is configured.

2. Choose the right profile

Before opening a workspace, switch to the profile that should own the work. Profiles keep credentials, git identity, model provider, and privacy defaults separate, so a client repo, work repo, and personal project do not share the same agent keys or commit identity.

The active profile also controls where worktrees are created. By default, a workspace lives under that profile's worktrees root, organized by repo:

~/.kalauz/worktrees/<repo>/<slug>

3. Open one workspace per task

Create a New workspace for the change you want Claude Code to handle. Kalauz creates a fresh branch and a separate git worktree for that workspace, equivalent to:

git worktree add -b kalauz/<slug> <worktree-path> HEAD

That separation is the important part of the Claude Code worktree workflow: each agent process starts inside its own worktree, with its working directory set to that workspace. It can change files, install dependencies, run scripts, and commit on its own branch without forcing you to stash work in the main repo.

For the deeper model, see Isolated workspaces.

4. Brief Claude like a teammate

Give Claude the task, acceptance criteria, and any constraints that matter. For unfamiliar code, turn on Plan mode so it inspects first and proposes an approach before editing.

Update the billing settings page so failed invoices show the retry date.
Keep the change scoped to the settings route. Add or update the relevant test.

Kalauz launches Claude through the same CLI path and session, then streams the run inside the workspace. The agent uses the worktree on disk, not a copied snapshot, so the files you inspect are the files Claude actually changed.

5. Review the diff in place

When Claude settles, open the Diff tab. Kalauz watches the worktree and shows the change set against the base branch, so the review is tied to the real git state in that workspace.

Use inline comments for specific fixes and submit them back to the agent for another pass. Run your project's test or run command from the workspace before opening a PR.

6. Ship or archive the workspace

If the change is ready, follow the normal issue-to-PR workflow: create the PR, review checks, merge the workspace, then archive it. If the work is not worth keeping, archive the workspace and leave your main checkout untouched.

What's next?