How-to Guides

Review AI-generated pull requests

Review AI-generated pull requests by keeping the agent's branch, diff, tests, and revision loop in one workspace. In Kalauz, every workspace has its own branch and worktree, so you can inspect the change in place, run scripts before opening the PR, and send review comments back to the agent for another pass.

1. Start from an isolated workspace

Create a workspace for the task or issue you want the agent to implement. Kalauz cuts a branch and git worktree for that workspace, separate from your main checkout and separate from any other agent work in flight.

That isolation matters for review: the diff you read belongs to one task, the files on disk match that branch, and a failed experiment stays inside its own worktree. See Isolated workspaces for the git model in detail.

2. Read the diff before the PR exists

Open the Diff tab in the workspace detail panel. It shows the change set against your base branch, so you can review the AI-generated code before it is pushed as a pull request.

Use the surrounding tabs when the diff alone is not enough:

  • All files for the full worktree tree.
  • Changes for the files added, modified, deleted, or renamed by the agent.
  • Diff for line-by-line review in unified or split view.

This keeps the review close to the actual working tree instead of forcing you to switch between a chat transcript, an editor, and a PR page. For the full review surface, see Review and merge a workspace.

3. Run the project checks

Before opening the PR, run the workspace's Run script or an ad-hoc command from the console panel. The command runs inside the workspace worktree, so test output matches the files you are reviewing.

For most repos, the Run script is your dev server or test command. You can set it per project, put it in kalauz.json, or use the detected default. See Testing for setup scripts, run scripts, and terminal usage.

pnpm test

4. Send review comments back to the agent

When something is wrong, leave inline comments on the diff and submit them back to the agent. The comments include the file, line, code, and your note, so the agent can revise the same worktree instead of starting from a vague follow-up prompt.

Use comments for concrete review feedback:

This branch handles the empty state, but it does not preserve keyboard focus
after the Escape path. Add a regression test for that case.

After the agent revises, read the updated diff and rerun the checks. Repeat this loop until the branch is ready for a human PR review or merge.

5. Create the pull request

When the diff and checks look right, click Create PR. Kalauz briefs the agent with the worktree state, changed files, branch, and base branch, then the agent pushes the branch and runs gh pr create.

Creating PRs uses the GitHub CLI, so make sure gh is installed and authenticated (gh auth login).

6. Keep credentials separate with profiles

Profiles keep each workspace rooted in the right local context. Each profile carries its own credentials, git identity, model provider, and privacy defaults. The active profile also controls the worktrees root, and Kalauz applies that profile's git identity to the workspace's local git config.

Use separate profiles when you need different credentials, git identity, model provider, or workspace roots for different projects. For provider setup, see Configure model providers.

What's next?