How-to Guides

From issue to PR

Take a GitHub issue from description to an open pull request in one workspace.

This is the canonical Kalauz loop on a real task. Start from an issue, let an agent implement it in an isolated workspace, review the diff, and open the PR — without leaving the window.

1. Open a workspace for the issue

With your project selected, create a New workspace (⌘N). It gets its own branch and worktree, so this work can't disturb anything else you have in flight.

2. Brief the agent

Paste the issue into the chat — the title and body, or just the issue URL and a sentence of intent. Be explicit about scope and acceptance criteria; the agent does best with the same context a teammate would want.

Implement GH #142: "Search box doesn't clear on Escape."
Pressing Escape while the search box is focused should clear the
query and blur the input. Add a test.

For an unfamiliar area, turn on Plan mode so the agent proposes an approach before it edits.

3. Review the change

When the agent settles, open the Diff tab to read the change set against your base branch. Leave inline comments on specific lines and submit them back to the agent for another pass. Run your Run script or test command to confirm it works.

4. Open the PR

Hit Create PR. Kalauz hands the agent a brief of the worktree state — branch, base, changed files — and the agent pushes the branch and runs gh pr create against your base branch, keeping the title and description tight.

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

5. Merge and move on

Once checks are green and review is done, merge the workspace and archive it. The branch lands on your base; Kalauz folds the workspace away.

What's next?