Getting Started

Getting Started

Prerequisites

• Python 3.11+ and uv.
• git and the GitHub CLI (gh) authenticated, if you want factory runs to open and merge PRs.
• At least one AI coding agent CLI:
  • Claude Code (recommended)
  • OpenAI Codex
  • Or the optional SDK adapter: uv tool install "kstrl[sdk]" and set agent.type = "claude-sdk" (opt-in only; never auto-selected).
• POSIX (macOS or Linux). Windows is unsupported for concurrent worktrees.

Install

uv tool install kstrl      # installs `ks` and `kstrl`
# development install:
# git clone https://github.com/0xfauzi/kstrl.git && cd kstrl && uv tool install -e .

Scaffold a project

cd your-project
ks init .

This writes kstrl.toml (config), scripts/kstrl/prompt.md (the engineer prompt), and scripts/kstrl/prd.json (what to build: user stories with acceptance criteria). Edit the PRD first - it is the contract every adversarial role reviews against.

Run the single-component loop

ks run 25        # up to 25 engineer iterations, with mechanical verification

Run the full factory

ks decompose --spec spec.md   # architect red-teams the spec -> manifest + PRDs
ks factory --spec spec.md     # decompose + build every component through the gauntlet
ks factory --manifest .kstrl/manifest.json   # resume an existing run

The spec can be a single markdown file or a SpecKit artifact directory (spec.md required; plan.md and tasks.md used when present). If the architect finds blocker-severity spec issues it halts with exit code 2 - fix the spec; there is no override flag.

Other verbs: ks understand (read-only codebase mapping), ks feature (understand-then-implement for one feature), ks retry <component-id>, ks evolve (propose harness improvements from run history), ks config show.

Watch it work

• Bare ks opens the home shell: a run browser and command launcher.
• Long-running commands open their live dashboard automatically on a terminal (--no-tui or KSTRL_NO_TUI=1 opts out).
• ks dash attaches a read-only dashboard to any run - live or finished - from another terminal.
• ks status prints machine-stable state for scripts and CI.
• ks sense runs the mechanical checks by hand against any tree, with no PRD, branch, worktree or agent spend (--json for scripts).
• To understand what you are watching, open the live system atlas and step through the journey "A spec becomes a merged pull request".

Everything shown is a projection of .kstrl/runs/<run_id>/events.jsonl; the files are the record.

What to expect from a run

The agent will say it is done before kstrl agrees. That is by design: the agent's flag is a claim, and mechanical checks, an independent reviewer and a security reviewer measure the work before anything merges. When they disagree, the agent is handed the parsed failures and tries again; when a bound is reached (iterations, time, tokens, cost) the run stops and says why. Read Vision and Philosophy for the reasoning, and docs/runbook.md for what to do when a run halts.

Verify a development install

uv run pytest tests/ -v
uv run mypy kstrl/ --strict
uv run ruff check kstrl/ tests/
# opt-in, uses real LLMs:
KSTRL_RUN_CALIBRATION=1 uv run pytest tests/test_calibration.py -v

Configuration essentials

Precedence: CLI flag > KSTRL_* env > kstrl.toml > defaults. The keys you will touch first:

[agent]
type = ""              # auto: prefers claude-code, falls back to codex

[factory]
max_parallel = 4       # parallel component builds (worktree-isolated)
max_retries = 3
create_prs = true
pause_before_pr_merge = false   # the optional human checkpoint (E6)
max_adversarial_calls = 0       # 0 = unbounded; shared review/security/distill budget
max_total_tokens = 0            # run-level token budget

[security]
mode = "advisory"      # skip | advisory | hard

Full reference: kstrl.toml.example, docs/env-vars.md, and the operator recovery guide in docs/runbook.md.