Reference

Agent behavior

The exact rules an agent runs under inside a Kalauz workspace.

This is the reference for what happens when Kalauz launches an agent. Reach for it when you need precise behavior rather than the conceptual overview.

Working directory

The agent process is launched with its working directory set to the workspace's worktree. It cannot read or write another workspace's directory, and Kalauz does not share conversation state between sessions.

How Claude is invoked

Kalauz drives the claude CLI in streaming mode, building the invocation from your session settings. The flags it sets include:

--print
--input-format stream-json
--output-format stream-json      # bidirectional control protocol
--include-partial-messages
--model <id>                     # e.g. opus, sonnet, claude-opus-4-7[1m]
--effort <low|medium|high|max>
--permission-mode plan           # only when Plan mode is on
--dangerously-skip-permissions   # default, when Plan mode is off
--resume <session-id>            # follow-up turns in the same session
--fast                           # only when Fast mode is on
--append-system-prompt <text>    # the project's system prompt, if set

Codex runs through the codex CLI with the equivalent options; effort max maps to high there. Provider is chosen from the selected model — see Agent modes.

Input and output

Input is sent as stream-json and can carry multimodal parts — text plus images or documents you paste in. Output streams back as events: text deltas, tool use, the session id, and permission requests in Plan mode. Stdin stays open so Kalauz can answer permission prompts, and closes when the turn's result arrives.

Permissions

  • Plan mode on — --permission-mode plan. The agent asks before tool use; Kalauz routes your approvals back over the control protocol.
  • Plan mode off (default) — the agent acts autonomously. This is safe precisely because the worktree is sealed off from the rest of your disk.

Git operations

The agent commits freely on its own branch and pushes when you create a PR (gh pr create). Branch history is scoped to the workspace and never touches your base branch until you explicitly merge. Kalauz watches the worktree for changes — ignoring .git, node_modules, bin, obj, .vs, and target — and reconciles the diff and file tree live.

Environment

Each run gets a merged environment: the active profile's CLI config and credentials first (CLAUDE_CONFIG_DIR, the Claude OAuth token or API key), then your own variables from settings, then any org-managed variables. Managed settings can also pin the model and the claude binary path, and enable enterprise data-privacy mode.

Lifecycle hooks

  • On create — the project's setup script runs in the new worktree.
  • On archive — the optional archive script runs before the workspace is folded away.

See Testing for configuring these.