kkt

kkt models coding-agent decisions as a constrained optimization problem: implementation choices are decision variables, repository and product requirements define the feasible region, and an objective ranks the feasible candidates. It is named after the Karush–Kuhn–Tucker (KKT) conditions, the standard first-order conditions for constrained nonlinear optimization.

How It Works

Without kkt:

request --> agent --> plan --> edits --> validation


With kkt:

request --> agent --> constrained decision model --> edits --> validation
                                  |
                                  v
          objective + variables + constraints + validation evidence

Mathematical Basis

A constrained optimization problem in standard form is:

minimize    J(x)
subject to  g_i(x) <= 0,  i = 1, ..., m
            h_j(x)  = 0,  j = 1, ..., p

Here, x is a decision vector, J(x) is the objective, and the constraints define the feasible set. Its Lagrangian is:

L(x, λ, ν) = J(x) + Σ λ_i g_i(x) + Σ ν_j h_j(x)

Under differentiability and an appropriate constraint qualification, a local optimum satisfies the KKT conditions:

stationarity:            ∇J(x*) + Σ λ_i∇g_i(x*) + Σ ν_j∇h_j(x*) = 0
primal feasibility:      g_i(x*) <= 0 and h_j(x*) = 0
dual feasibility:        λ_i >= 0
complementary slackness: λ_i g_i(x*) = 0

These conditions distinguish feasibility from optimality and identify the binding constraints that shape a solution. They are generally necessary conditions for a local optimum; under convexity assumptions they can also be sufficient.

kkt transfers that structure to software decisions:

Mathematical concept	Coding-agent interpretation
decision vector x	an implementation candidate: files, APIs, data flow, and validation choices
objective J(x)	preference misalignment, semantic change surface, residual risk, complexity, and cost
feasible set	candidates that satisfy required behavior, contracts, invariants, safety rules, and validation gates
binding constraint	a requirement that materially limits the implementation choice
candidate optimum	the preferred feasible candidate among those examined
validation	empirical evidence supporting the claim that the implementation is feasible

The operational model is therefore:

F = {x in X_considered |
       requested behavior is complete
       and public contracts and repository invariants are preserved
       and safety requirements and required validation gates hold}

choose x_hat in F by ordered objectives:
  1. place behavior at its architectural or invariant owner
  2. minimize semantic production change
  3. minimize residual risk and unnecessary complexity
  4. use implementation cost as a tie-breaker

This is a reasoning framework, not a numerical solver. It therefore claims neither exhaustive search nor global optimality.

Software implementation spaces are mostly discrete, conditional, and non-convex. For that reason, $kkt-deep also borrows search techniques from constraint programming: explicit decision domains, constraint propagation, conditional constraints, conflict recording, candidate pruning, bounded search, and falsification. It does not execute CP-SAT. In short, constrained optimization supplies the decision model; constraint programming inspires parts of the search procedure.

Install

Recommended install:

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:

npx @dannylee1020/kkt upgrade

To target one agent explicitly, use --target as an override:

npx @dannylee1020/kkt install --target claude
npx @dannylee1020/kkt upgrade --target codex

Choose a CLI install location:

npx @dannylee1020/kkt install --bin-dir ~/.local/bin

Alternative shell installer:

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 decision problem: define the objective, identify the boundaries that cannot move, reject known-infeasible candidates, compare the viable candidates examined, and specify the evidence needed to validate the result.

Instead of:

build xyz

kkt pushes the agent toward:

what is the strongest feasible implementation we can justify,
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 candidates that violate hard constraints, compare the remaining candidates against ordered objectives, choose the best-supported path examined, then validate it against the model.

Benchmark

We tested Vanilla, Plan, KKT, and KKT Deep on 13 SWE-bench Verified tasks: 2 easy, 6 medium, and 5 hard. Within each campaign, every workflow used the same tasks, model configuration, resources, and official SWE-bench evaluator.

Mode	Resolved	Tokens	Production LOC
vanilla	9/13	11.30M	280
plan mode	9/13	15.98M	296
kkt	9/13	15.84M	249
kkt-deep	10/13	21.41M	305

KKT matched Vanilla's solve rate with 11% less code churn. KKT Deep solved one additional hard task for the best overall result. Both used more tokens, showing a tradeoff between compute and stronger implementation discipline. See the results and methodology.

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	Preferred feasible implementation among the candidates examined
What comes before edits?	Exploration, questions, and an agreed plan	Provisional constraints, feasibility, chosen path, and required validation evidence
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 execution bounds, stop conditions, and approval state
When is it enough?	Small or straightforward work	Work where boundaries, contracts, tradeoffs, or validation evidence 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, "Which feasible implementation is best supported by the constraints, objectives, and available evidence?"

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, candidate selection, execution bounds, or validation:

initial intent
  -> quick repository grounding
  -> provisional objective and constraint frame
  -> targeted owner clarification, if needed
  -> complete discovery and reject infeasible candidates
  -> select the preferred candidate and identify 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:

$kkt <feature, bug fix, or refactor>

Use the deeper workflow when the task needs it:

$kkt-deep <architecture, tradeoff, or complex implementation>

$kkt and $kkt-deep are separate end-to-end skills. $kkt does not invoke, load, or delegate to $kkt-deep; when compact modeling is insufficient, it explains the trigger and waits for the user to choose $kkt-deep. $kkt-deep performs its own modeling, approval, implementation, and validation.

Skill invocation syntax varies by agent:

Codex:       $kkt, $kkt-deep
Claude Code: /kkt, /kkt-deep
Pi:          /skill:kkt, /skill:kkt-deep
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-deep	architecture choices, tradeoffs, and complex implementation	approved deep model, implementation, and validation	optional .kkt/model/<slug>/

Execution ownership and delegation

KKT keeps the daily path lightweight:

• $kkt uses the main agent for discovery and implementation; it does not delegate by default.
• $kkt-deep may use bounded read-only delegation for independent modeling discovery or challenge only when the current harness exposes a compatible native capability and the coordination benefit outweighs its cost. Investigation tracks are generated from the model rather than hardcoded as agent personas; the main agent reconciles their evidence and owns approval, implementation, and final validation. Without that capability, it continues alone.

KKT's CLI remains a deterministic state control plane. It does not spawn agents, route skills, or merge delegated changes. Delegated investigations receive bounded read-only briefs and cannot ask user questions, mutate project or .kkt/ state, grant approval, select the model, implement changes, or replace final validation.

All candidate search is correctness-first: complete request coverage, public contracts, and repository-evidenced invariants are the feasibility gate. Among feasible candidates, KKT prefers repairing the invariant at its owner and changing the smallest semantic production surface, then uses production LOC as a tie-breaker. Required validation and safety behavior are part of completeness; raw LOC never makes an unverified solution preferable.

For ordinary bug fixes, KKT uses a compact causal trace — symptom → producer → invariant owner → consumer → sibling implementations/tests — and performs a focused owner-level or disconfirming check before approval when a plausible alternative remains. After correctness is established, it may remove unnecessary production hunks and rerun the affected checks.

Both active skills require explicit approval before mutation and finish with validation evidence.

kkt turns rough input into an intent frame:

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:

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 required validation evidence. Routine work uses a compact contract; complex or high-risk work uses the deep contract.

Expected final audit:

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, execution bounds, approval, validation evidence, and workflow progress.

Reference command groups:

# workspace creation
kkt start plan|model "<request>"

# record planning and validation state
kkt intent
kkt discovery
kkt model
kkt evidence

# workflow transitions and diagnostics
kkt done
kkt block
kkt status
kkt show model

Run kkt help for exact syntax. The active skills remain chat-first; durable model workspaces store intent, discovery, model, and evidence under the project root's .kkt/ directory. Legacy run/loop CLI commands may remain available for compatibility but are no longer documented or packaged as skills.

Validation evidence

KKT is a workflow guide and state recorder, not a sandbox. Both active skills own implementation after approval and must report validation commands, checks, artifacts, or an explicit validation limitation. Durable model workspaces preserve the reasoning and evidence needed for handoff without introducing a separate execution skill.

License

Apache-2.0