Run your first AI coding mission with Kranz

1. Install Kranz and your agent runtime

You need Git, a Git repository to work in, and an installed, authenticated agent runtime. Claude Code is the default.

This walkthrough builds the current source, including fixes made after the latest packaged release, and requires Rust 1.88 or newer. Prebuilt binaries are also available; see the installation options and supported platforms.

git clone https://github.com/craigcode/kranz.git
cargo install --path kranz/crates/cli --locked

Kranz uses your existing agent runtime; it does not install it or sign you into a vendor account. See the backend setup guide for supported runtimes and their authentication requirements.

2. Prepare the repository

In the repository you want the agent to change, initialize Kranz:

cd /path/to/your/repo
kranz init

kranz init detects common Rust, Node, and Python checks and creates the repository setup. Review the generated .kranz/merge-gates.json: its commands should match the checks you actually require before accepting work. For another toolchain, supply a check explicitly, such as kranz init --gate "make verify".

Review and commit the setup files reported by init, including the runtime ignore rules and merge policy. Then check readiness:

kranz ready

Resolve readiness findings before starting. Backend, model, authentication, and sandbox support affect which roles can run.

3. Plan one checkable change

Choose a goal with a clear expected result. For example, in a service that already has an HTTP test suite:

kranz plan "Add a GET /health endpoint that returns 200 and a JSON status, with an integration test"

This starts an agent planning session using your configured runtime. Hosted providers may incur charges. Discuss the scope, then use /plan in the interactive session to render the proposal and cost estimate. Before approving, check the acceptance criteria, files in scope, test commands, and budget. Approval commits the plan to a new mission branch.

A useful criterion names an observable behavior. “The endpoint returns the agreed JSON and its integration test passes” gives the reviewer something concrete to verify.

4. Run and follow the mission

After approval, the planner offers to start execution immediately. If you chose to defer it, start the mission from the same repository:

kranz run

Workers implement the planned features, and validators review milestone results. In the default worktree mode, implementation happens in a separate Git worktree. Usage and costs depend on your configured runtime.

From another terminal in the same repository, open the dashboard:

kranz serve --open

For a one-time terminal status report instead, use kranz status.

Prefer to operate from a Slack thread? Follow the optional Slack setup and usage guide to connect the same host for planning, approvals, and updates.

Use the mission view to follow progress, review findings, and steer the work. A blocked or failed mission needs attention; read the recorded reason before resuming.

5. Review before merging

A complete mission is ready for your review. Compare the actual diff with the approved plan, read the validation results, and check any remaining caveats. The dashboard’s Merge action runs the repository’s merge gates against the proposed integration before advancing the local base branch.

Ordinary mission execution and merging stay local. Push reviewed work through your normal Git workflow when you are ready.

Continue with reviewing agent changes, or read the CLI quick start for more ways to steer a mission.