Concepts

Workflow

The end-to-end loop in Kalauz, from adding a repo to shipping a PR.

Everything in Kalauz orbits one loop. Learn it once and the rest of the app is just detail.

Add a repo
  └─ New workspace ──▶ fresh branch + git worktree (fully isolated)
        └─ Launch an agent (Claude Code / Codex) with your existing login
              └─ Watch progress · review the diff · run setup/run scripts
                    └─ Open the PR and merge — all in one window

The states a workspace moves through

  1. Created. Kalauz cuts the branch and worktree, copies environment files, and runs the setup script.
  2. Active. The detail panel loads — file tree, changes, diff — and a file-system watcher keeps the sidebar badge live (it refreshes a few times a second while files change).
  3. Running. Whenever any chat in the workspace is mid-turn, the workspace shows a running indicator in the sidebar.
  4. Ready. The agent settles; the header shows a status like 4 changes or 2 ahead of main.
  5. Archived. Once merged (or set aside), the workspace is archived and folded out of the active list. The worktree is kept on disk.

Where each step happens

  • Sidebar — projects and their workspaces; the control room view of the whole yard.
  • Chat — where you brief the agent and watch it work. A workspace can hold several chat sessions.
  • Detail panel — All files, Changes, and Diff tabs, plus the console panel (Setup / Run / Terminal) along the bottom.
  • Command palette — press ⌘K (Ctrl+K on Windows/Linux) to jump anywhere or fire an action — New session, New workspace, Archive, Toggle theme, and more.

Keeping the loop tight

  • Give each workspace a single, well-scoped task.
  • Review and merge little and often so branches don't drift.
  • Let Kalauz reap worktrees on archive instead of cleaning up by hand.

What's next?