![kkt](assets/kkt-readme-modern.png)

Start modeling your implementation

ci status security status release version license: Apache 2.0

kkt applies [constrained optimization](https://en.wikipedia.org/wiki/Constrained_optimization) to coding-agent workflows. Named after the [Karush-Kuhn-Tucker conditions](https://en.wikipedia.org/wiki/Karush%E2%80%93Kuhn%E2%80%93Tucker_conditions), it translates mathematical modeling discipline into a practical framework for identifying application constraints, choosing feasible implementation paths, and validating the result. ## How It Works ```text Without kkt: request --> agent --> plan --> edits --> validation With kkt: request --> agent --> kkt(optimization modeling) --> edits --> validation | v objective + constraints + decision variables + proof ``` ## The Model The core idea: ```text choose x in X maximize alignment(user_goal, x) subject to C_app(x) C_arch(x) C_data(x) C_ui(x) C_infra(x) C_validation(x) ``` where: - `x` is the implementation decision vector - `X` is the feasible implementation region - `C_*` are application constraints - the selected plan is the best feasible plan, not the first plausible plan - validation is the certificate that the selected plan satisfies the model kkt does not implement a literal numerical solver. It borrows the discipline of constrained optimization and applies it to coding-agent decisions: feasibility first, optimization second, validation as the certificate. ## Install Recommended install: ```bash npx @dannylee1020/kkt install ``` This automatically detects all supported agents available on your system and installs the kkt skills for each one: - Claude Code: `~/.claude/skills` - Codex, Pi, and OpenCode: `~/.agents/skills` Upgrade kkt with the same automatic detection: ```bash npx @dannylee1020/kkt upgrade ``` To target one agent explicitly, use `--target` as an override: ```bash npx @dannylee1020/kkt install --target claude npx @dannylee1020/kkt upgrade --target codex ``` Choose a CLI install location: ```bash npx @dannylee1020/kkt install --bin-dir ~/.local/bin ``` Optionally, install hooks for more reliable, deterministic guardrail flow. **This feature is still in beta**. ```bash npx @dannylee1020/kkt install --hooks ``` Alternative shell installer: ```bash curl -fsSL https://raw.githubusercontent.com/dannylee1020/kkt/main/scripts/install.sh | bash ``` The CLI uses a release binary when available, or builds from source with Go. Use `KKT_VERSION` to pin a release tag, or `KKT_BINARY_URL` to install from an explicit binary URL. ## Why kkt Most coding-agent workflows turn a request into a plan. That helps, but it carries risk: the plan focuses on what to change, not what must stay unchanged. kkt shifts the frame from planning to modeling, so the solution is built around the constraints already present in the codebase. It treats implementation as a constrained optimization problem: define the objective, mark the boundaries that cannot move, compare the viable paths, and name the proof that will make the result credible. Instead of: ```text build xyz ``` kkt pushes the agent toward: ```text what is the best feasible implementation, given what must stay true? ``` For coding agents, "what must stay true" is usually concrete: - public contracts and API behavior - architecture boundaries - files, modules, endpoints, schemas, and migrations - security, privacy, and data-integrity rules - UI and product boundaries - infrastructure and runtime limits - validation evidence required before completion The value is forcing feasibility before optimization: reject plans that violate hard constraints, compare the remaining plans, choose the best feasible path, then validate against the model. ## kkt vs plan mode kkt can replace plan mode, or it can run after plan mode to harden a rough plan. Default plan mode already provides read-only exploration, clarification, alternatives, and approval. kkt adds an explicit feasibility model and carries it into execution. | question | default plan mode | kkt | | --- | --- | --- | | What is it optimizing for? | Coordination and sequencing | Best feasible implementation | | What comes before edits? | Exploration, questions, and an agreed plan | Provisional constraints, feasibility, chosen path, and validation proof | | How are assumptions handled? | Usually remain narrative | Verified or marked as assumptions | | How are alternatives selected? | Discussed and recommended | Hard-constraint violations rejected before feasible options are compared | | How is execution bounded? | Primarily by the approved plan | Model-derived paths, guardrails, stop conditions, and approval state | | When is it enough? | Small or straightforward work | Work where boundaries, contracts, tradeoffs, or proof matter | | Where does state live? | Usually chat context | `$kkt` is chat-first; durable `.kkt/` state is opt-in or used by deeper workflows | Plan mode asks, "What should we do?" kkt asks, "What is the best feasible implementation, given what must stay true?" ### Constraint-driven clarification KKT does not add a generic interview before modeling. It uses a short, read-only grounding pass to build a provisional frame, then asks only questions that can change feasibility, scope, the selected optimum, guardrails, or validation: ```text initial intent -> quick repository grounding -> provisional objective and constraint frame -> targeted owner clarification, if needed -> complete discovery and reject infeasible candidates -> select optimum and binding constraints -> derive and approve the execution plan ``` Clear work can proceed without questions. Imported completed models do not repeat intake unless new evidence causes material drift. ## Quick Start Most users start with `$kkt`: ```text $kkt ``` Use the deeper workflows when the task needs them: ```text $kkt-model $kkt-run $kkt-loop ``` For a large change, model once and choose the execution strategy afterward: ```text $kkt-model $kkt-run # bounded implementation # or $kkt-loop # durable iterative implementation ``` Skill invocation syntax varies by agent: ```text Codex: $kkt, $kkt-model, $kkt-run, $kkt-loop Claude Code: /kkt, /kkt-model, /kkt-run, /kkt-loop Pi: /skill:kkt, /skill:kkt-model, /skill:kkt-run, /skill:kkt-loop OpenCode: ask OpenCode to use the relevant kkt skill ``` ## Choose a Workflow | workflow | use it for | what it produces | durable state | | --- | --- | --- | --- | | `$kkt` | normal feature work, bug fixes, and refactors | compact optimized plan and implementation | none by default | | `$kkt-model` | architecture choices and tradeoff analysis | detailed reusable model | `.kkt/model//` | | `$kkt-run` | bounded implementation | approved execution with guardrails | `.kkt/run//` | | `$kkt-loop` | long-running or iterative work | resumable execution and evidence | `.kkt/loop//` | Run and loop workflows require an approved execution plan. They can either model fresh work or import a completed model. kkt turns rough input into an intent frame: ```text user goal desired behavior user-visible success scope boundary explicit user constraints ``` The user does not need to provide all of this upfront. Repo constraints, affected files, and validation paths are discovered from the codebase when possible and marked as assumptions when needed. When kkt is invoked after a prior plan, it treats the plan as untrusted scaffold: ```text plan output --> extract signals --> classify claims --> verify facts --> optimize kkt model ``` Plan claims do not become kkt facts until it verifies them or explicitly carries them as assumptions. Before edits, every selected model must define its objective, constraints, feasible choice, selected plan, and validation proof. Routine work uses a compact contract; complex or high-risk work uses the deep contract. Expected final audit: ```text Objective: satisfied Hard constraints: satisfied Binding constraints: respected Validation evidence: tests, checks, artifacts, or reason validation was not possible Residual risk: remaining uncertainty ``` ## CLI and State Most users do not need to run the CLI directly. The installed skills use it as a deterministic control plane for durable state, guardrails, approval, validation evidence, and workflow progress. Reference command groups: ```bash # workspace creation kkt start plan|model|loop|run "" kkt run from-model [model-workspace] kkt loop from-model [model-workspace] # record planning and execution state kkt intent kkt discovery kkt model kkt guardrails set '' kkt guardrails configure --allowed '' --command '' kkt plan kkt task kkt criteria kkt progress kkt evidence # workflow transitions kkt approve kkt next kkt resume kkt validate --run kkt done kkt block # diagnostics and beta hook integration kkt status kkt show kkt judge kkt replay kkt hooks kkt hook ``` Run `kkt help` for exact syntax. Workflow transitions enforce readiness automatically; use diagnostics when a transition is blocked. Use `kkt start run` for direct bounded execution or `kkt run from-model` to import a completed model. `kkt status --json` provides machine-readable workflow state. `kkt guardrails configure` updates common guardrails without requiring a complete JSON contract. Ordinary `$kkt` tasks stay chat-first. Durable workflows store their state, guardrails, and evidence under the project root's `.kkt/` directory. ## Hooks Coding agents can run hooks around tool use. kkt's hook adapters plug into those agent hook systems so an approved `run` or `loop` workspace can enforce its guardrail boundaries while the agent is editing. Before and after tool execution, the adapter asks the current project whether the proposed or actual file mutation stays inside modeled `allowed_paths` and away from `blocked_paths`. If hooks are not installed or not armed, normal agent behavior is unchanged. If hooks are armed, out-of-scope edits can be blocked deterministically instead of relying only on the agent to remember checkpoints. > [!WARNING] > Hooks are beta and installed separately because they modify coding-agent runtime behavior. ## Testing hook adapters Run the isolated installer matrix with: ```sh task test-install-hooks ``` Run real-runtime enforcement tests with an installed agent runtime: ```sh task test-runtime-hooks RUNTIME=pi task test-runtime-hooks RUNTIME=opencode ``` The runtime runner builds the local `kkt` binary, uses an isolated temporary project, and drives a local deterministic model server. OpenCode is installed through `npx` at version `1.18.4` when it is not already available. ## License Apache-2.0