How a task runs

You type a request. Kiehl decides whether it is a quick edit or a real change.

• A small, clear edit (a typo, a rename, a one-line fix) is just made.
• Anything bigger — several files, a design decision, or an unclear request — kiehl asks once whether you want a plan first. Say no and it carries on directly. Say yes and the request goes through the steps below.

The four steps

Step	What happens	You see
Scout	Reads the relevant code and works out what you actually want. Read-only.	Questions, one at a time, with a suggested answer. It only asks what the code can’t tell it.
Plan	Writes a plan in a plan file, based on the scout’s brief. Read-only except for that file.	The plan, and a prompt to approve it or send feedback. It revises until you approve.
Build	Makes the edits in order, running each step’s checks as it goes.	Edits and command output as they happen.
Review	Compares the result to the plan and runs the plan’s verification.	A final report after review.

If review finds gaps, they go back to build once as a short list of fixes. If a fix round has already been used, kiehl reports what is still missing instead of looping.

The check before review

When build finishes, kiehl runs your project’s check. If it fails, kiehl tries to fix it. After two failed attempts it moves on to review and says the check is still failing, so a broken check can’t trap a session.

The command comes from the verify: line in your AGENTS.md, or the test command kiehl detects (Go, Bun, pytest and so on). verify: none turns it off. The check applies to planned changes, not to quick edits.

What it can do without asking

By default kiehl works without stopping to ask. It can read and edit files in your project and run shell commands. It asks first when:

• it wants to touch a file outside your project folder;
• it wants to read a .env file (.env.example is fine);
• it is repeating the same call over and over.

Scout, plan and review can’t edit your code at all. Only build can. To make kiehl ask more often, set permission rules in your config.

Kiehl also has a read-only git tool for status, diff and log. A command that hangs is stopped, and any background process it started is cleaned up.

Reviewing what changed

The sidebar lists every file changed in the session, with lines added and removed. Open the diff viewer for the full change. Kiehl doesn’t commit for you.