Run Codex CLI in isolated git worktrees

Run Codex CLI in Kalauz by opening a workspace: Kalauz creates a branch plus an isolated git worktree, launches the codex CLI already on your PATH, and keeps the resulting diff reviewable in place.

That gives each Codex session its own working directory and git identity while you keep normal review control over the branch before it lands.

1. Start from a real repo

Install Kalauz, make sure git and codex are available on your PATH, then add the repository you want Codex to work in. Kalauz does not replace the Codex CLI or require a separate API path; it runs the local CLI from inside the workspace.

If Codex is not connected yet, run codex login and check model provider settings before you start the workspace.

2. Open an isolated workspace

Create a New workspace for the task. Kalauz creates a branch and a separate git worktree under the active profile's worktrees root, outside your primary checkout.

In git terms, the workspace is the equivalent of:

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

The important property is isolation: Codex edits files in that worktree, not in your main checkout and not in another agent's workspace.

Screenshot — placeholderA Codex workspace with its kalauz/... branch and worktree path visible.

3. Pick the right profile

Use profiles when the same machine needs different defaults for different work: separate credentials, git identity, model provider, and privacy defaults. The active profile determines the worktrees root and the local git user.name / user.email applied to the workspace.

This matters for Codex CLI workflows because the agent inherits the workspace environment and runs as a normal process. See agent behavior for the launch model and agent modes for per-session model and effort choices.

4. Give Codex a scoped task

Brief the agent with the same constraints you would give a teammate: branch intent, acceptance criteria, files or tests to inspect, and anything out of scope.

Use Codex to implement GH #142 in this workspace.
Scope: search input behavior only.
Acceptance: Escape clears the query, blurs the input, and has a focused test.
Do not change navigation or styling.

For risky or unfamiliar code, start in Plan mode so Codex proposes an approach before editing.

5. Review the diff in place

When Codex settles, open the Diff tab and review the changes against the workspace base. Kalauz watches the worktree, so file edits appear without moving you out of the review surface.

Leave inline comments on specific lines and send them back to Codex for another pass. Run your normal test or run command in the workspace before opening a PR.

6. Land the branch deliberately

The branch does not touch your base branch until you merge it. After review, open the PR from the workspace, wait for checks, then merge the workspace and archive it.

For the broader Kalauz model, start with the docs home or the homepage. For the next practical step, follow From issue to PR.