@dannylee1020/kkt

kkt applies constrained optimization to coding-agent workflows. Named after the Karush-Kuhn-Tucker 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

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:

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.

$kkt-deep also applies CP-SAT-inspired constraint-search discipline through agent reasoning: explicit decision domains, conditional constraints, feasibility propagation, conflict recording, bounded candidate search, and falsification. It does not run CP-SAT or claim globally proven optimality.

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 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:

build xyz

kkt pushes the agent toward:

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.

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	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 execution bounds, 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, 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 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:

$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 validation proof. 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