AI coding agent workspace setup

Set up an AI coding agent workspace by giving each task its own git worktree, a predictable setup script, a runnable verification command, and a profile with the right credentials and defaults. In Kalauz, that means one isolated workspace per task, agents launched through your existing claude or codex CLI on PATH, and a diff you can review in place before anything reaches the base branch.

Kalauz is built for this loop: install it, add a project, create a workspace, let the agent work inside that workspace's branch and worktree, then review and merge the result.

1. Install the agent CLIs first

Kalauz does not replace your local agent tools or ask for a separate login. It drives the existing CLIs on your machine:

claude for Claude Code.
codex for Codex.
gh when you want Kalauz to help create pull requests.

Make sure the CLIs you plan to use are installed, authenticated, and available on your PATH. If Kalauz cannot find a provider CLI, its models are unavailable until the executable is installed or its path is configured.

Start with Install, then connect provider defaults in Configure model providers.

2. Add the repo as a project

Add the repository root as a project. Kalauz inspects the repo and pre-fills setup and run commands from common markers:

Marker	Setup script	Run script
`pnpm-lock.yaml`	`pnpm install`	`pnpm dev`
`yarn.lock`	`yarn install`	`yarn dev`
`package.json`	`npm install`	`npm run dev`
`.sln` / `.csproj`	`dotnet restore`	`dotnet run`
`pyproject.toml`	`uv sync`	-
`go.mod`	`go mod download`	`go run .`
`Cargo.toml`	`cargo fetch`	`cargo run`

Override these when your repo needs a narrower command. For a test-first workspace, the Run script can be the command you actually trust:

pnpm test

See Testing for the full script order, including project settings, kalauz.json, and auto-detection.

3. Keep each task in an isolated worktree

Create a New workspace for the task. Kalauz creates a branch and git worktree equivalent to:

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

The worktree lives outside your main checkout under the active profile's worktrees root, for example:

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

That is the workspace boundary. The agent process starts in that worktree, edits that directory, and cannot write another workspace's files. Build output, dependency installs, and uncommitted edits stay scoped to that workspace.

Screenshot — placeholderA Kalauz workspace showing its branch, worktree path, setup status, and diff tab.

Read Isolated workspaces for the deeper git model, or First workspace for the first-run flow.

4. Use profiles as the environment boundary

Profiles should separate the parts of agent setup that should not bleed between contexts:

Credentials and CLI config, such as Claude config directories or Codex auth.
Git identity, including the user.name and user.email applied to workspace-local git config.
Model provider defaults, default model, effort, and review model choices.
Privacy defaults, including managed enterprise data-privacy settings when your team uses them.

When Kalauz launches an agent, it builds the process environment from the active profile's CLI config and credentials, then your configured variables, then any org-managed variables. The same active profile also determines where worktrees are created and which git identity is applied locally.

For exact launch behavior, see Agent behavior.

5. Review the diff before shipping

Treat the workspace diff as the handoff point between the agent and you. Kalauz watches the worktree live, so the Diff tab reflects what is on disk while the agent works. You can run the setup or Run script, open files for context, leave inline comments, and send those comments back to the agent for another pass.

Nothing lands on your base branch until you merge the workspace. When the change is ready, use the review flow in Review and merge a workspace, or follow the end-to-end loop in From issue to PR.

Workspace checklist

Install and authenticate the provider CLIs you need.
Add the repository root as a Kalauz project.
Confirm the Setup script installs dependencies from a fresh worktree.
Set the Run script to the command that proves the change.
Use the right profile for credentials, git identity, model defaults, and privacy defaults.
Create one workspace per task so every agent gets its own branch and worktree.
Review the diff in place before merging or opening a PR.

What's next?

Install Kalauz - get the app and provider CLIs ready.
Testing - tune setup and run scripts.
Configure model providers - set CLI and model defaults.