Running krutrimbox

Every run must choose an Agent Backend with the required --agent flag (codex or claude). There is no default — a run never starts without an agent named explicitly.

Run one explicit Target Issue:

kb run --issue 1 --agent codex

Run batch mode for all eligible ready Target Issues, backed by Claude Code:

kb run --agent claude

If you are running from a clone of the repository instead of the globally installed binary, the same commands are available through the package scripts:

pnpm start run --issue 1 --agent codex
pnpm start run --agent claude

The Agent Backend is chosen per run. Because the Done Set is rebuilt from Refs #<number> commit footers on the agent-blind Target Issue Branch, you can even resume a Target Issue with a different agent than an earlier run used; each agent gets its own Target Issue Sandbox, whose name embeds the issue number, a repository fingerprint, and the agent (e.g. krutrimbox-issue-1-acme-webapp-1a2b3c4d-codex).

Choosing the base branch

krutrimbox always creates the Target Issue Branch from a clean origin ref, never from whatever your host happens to have checked out. By default that ref is your repository's default branch (whatever GitHub reports — main, dev, trunk, …). Pass --base-branch to start from a different origin branch:

kb run --issue 1 --agent codex                     # base = repository default branch
kb run --issue 1 --agent codex --base-branch dev   # base = origin/dev
kb run --agent claude --base-branch dev            # batch mode, all issues based on origin/dev

The chosen base drives both the branch creation and the Target Issue Pull Request base, so the PR always targets the branch the work was built on. This is useful when you keep main as a production branch and integrate day-to-day work on a branch like dev. If the named base branch does not exist on origin, the run stops with a clear error.

Because the branch is created from origin/<base-branch> (and resumed from origin/<branch>), a run is unaffected by your host working tree: you can be on any branch, with uncommitted changes or local commits that are not yet pushed, and none of that leaks into the Target Issue Branch.

Choosing the model

By default each Agent Backend runs whichever model its own CLI picks — Codex and Claude Code each ship a maintained default. Pass --model to choose one explicitly; the value is handed straight to the backend's own model flag:

kb run --issue 1 --agent claude --model opus       # Claude Code, Opus
kb run --issue 1 --agent codex  --model gpt-5-codex # Codex, a specific model
kb run --agent claude                               # no --model → backend auto-picks

--model is optional — unlike --agent, which is always required. The model name is passed through unchanged, so use whatever names your chosen backend accepts, and one run's model always belongs to that one backend (a run uses a single Agent Backend end to end). There is no allowlist: if you mistype a model, the backend rejects it and the run fails with a clear "model not found" error rather than silently falling back to a different model.

To review with a different model than you implemented with — for example implement with a fast model but review with a stronger one — set a per-step model on a hook Agent Action; see Configuration → Hooks.

Choosing the reasoning effort

--effort sets how much reasoning the model spends, the same way --model sets which model runs — optional, passed straight to the backend's own effort control:

kb run --issue 1 --agent claude --effort high   # Claude Code's --effort
kb run --issue 1 --agent codex  --effort xhigh  # Codex's model_reasoning_effort
kb run --agent claude                            # no --effort → backend default

The valid levels are backend-specific (for example Claude accepts low, medium, high, xhigh, max; Codex accepts minimal, low, medium, high, xhigh), and — like --model — the value is passed through unchanged with no krutrimbox-side list. An unrecognized level is left to the backend: Claude warns and falls back to its default; Codex either uses the nearest supported level or, for a level it doesn't recognize at all, fails the run. As with --model, a per-step effort on a hook Agent Action lets you review at a different effort than you implemented with (see Configuration → Hooks).

The model and effort krutrimbox passes are echoed in the run log (on the run's startup line and each agent-action line) so you can see what a run used — note this is what krutrimbox requested; neither backend reports the level it ultimately resolved to.

Which issues krutrimbox works on

krutrimbox works on issues assigned to you — the GitHub account gh is authenticated as — that carry the ready-for-agent label. An issue must be assigned to you alone; one assigned to someone else or to several people is skipped. Solo developers who don't assign issues can pass --implement-unassigned to also run issues with no assignee.

Batch discovery (kb run) finds open ready-for-agent issues assigned to you that have no parent issue. A child Implementation Issue can also carry ready-for-agent; the no-parent rule prevents it from being discovered as its own Target Issue. To work on your slice of an epic that belongs to a teammate, run the parent explicitly with kb run --issue <parent>. See Issue Ownership & Routing for the full model, including how teams split a parent's sub-issues across people.

A Standalone Target Issue has no attached sub-issues, so krutrimbox treats the Target Issue itself as a sequence-of-one Implementation Issue and implements its body directly. A Parent Target Issue has attached sub-issues — created with GitHub's native sub-issue feature — so krutrimbox uses the Target Issue body as context and walks those Implementation Issues in issue-number order.

TIP

krutrimbox reuses your issue titles verbatim: the Target Issue Pull Request title is the Target Issue title, and each commit subject is the title of the Implementation Issue it delivers — the sub-issue title for a Parent Target Issue, or the Target Issue's own title for a Standalone Target Issue. So if you write your Target Issue and sub-issue titles following your commit conventions (for example feat: add batch mode or fix: handle missing footer), your pull request title and every commit on the branch will follow those conventions automatically — with no extra step.

krutrimbox does not close issues during a run. Each successful AFK or HITL completion is recorded by a Refs #<issue-number> commit footer on the Target Issue Branch; the Done Set is rebuilt from those footers on every run and drives resume behavior. The Target Issue Pull Request body carries Closes #<number> keywords for the Target Issue and every Implementation Issue, so GitHub closes them when the pull request merges.

For the end-to-end mechanics of a run — sandboxes, commits, pull requests, HITL pauses, and lifecycle hooks — see Factory Flow.