v0.5.0 — demo · conflict-aware · plugins

AI agents commit broken code. klasp stops them locally — before the loop closes.

klasp blocks AI coding agents on your existing quality gates — no rewrites, no migration. See it work in one command, no repo required.

klasp demo shows the whole story; klasp setup wires it into your repo from git init to green doctor.

$cargo install klasp && klasp demo View on GitHub →

Live demo · klasp demo

Same agent. Same task. One difference.

This is what klasp demo replays in your terminal — a deterministic, pre-recorded gate session. No repo to enrol, nothing to configure.

without klasp agent-session · pid 8821

with klasp agent-session · pid 8822

auto-loops every 36 s

No surprises

A gate you can trust on the commit path.

✓ Fail-open by default

A parse error or version skew degrades to allow, with a notice on the surface — klasp never silently wedges your commits.

✓ Won't clobber your hooks

v0.5.0 fingerprints husky, lefthook, and pre-commit and skips with a warning instead of overwriting. klasp init --adopt mirrors what you already run.

✓ klasp gates klasp

The repo blocks its own agents on cargo check / clippy / test via a real klasp.toml — and so does this site.

✓ Proven, not promised

Every green cell in the agent matrix below is backed by a committed captured-session test, not a marketing claim.

✓ Honest about pre-1.0

Config and plugin schemas are versioned and stabilise at v1.0; breaking changes land only at minor boundaries, with migration notes. See the security model.

✓ Apache-2.0, one Rust binary

cargo / npm / pip. No telemetry, no account, no server in the loop.

Install

Pick your package manager.

cargo (rust)

$ cargo install klasp

npm

$ npm i -g @klasp-dev/klasp

pip (python)

$ pip install klasp

then $klasp setup

Use case · overnight autonomy

Ship while you sleep. Wake up to PRs, not panic.

Autonomous agents need a deterministic done signal. Without one, an overnight run drifts: retry loops, exhausted context, force-pushed broken commits. klasp is that signal — every iteration ends in a clean pass / fail with structured findings.

Without klasp overnight-run · pid 4471

23:42▸agent: implement checkout flow

00:15✗tests fail · agent guesses, retries with different approach

01:33✗lint errors · agent rewrites unrelated module

02:50✗stuck in test/lint loop · context window exhausted

04:12✗agent gives up → force-pushes broken code

07:00⨯main is red. 47 failed CI runs. 6h of compute burned.

With klasp overnight-run · pid 4472

23:42▸agent: implement checkout flow

23:58●klasp:format ✗ → 3 lines · agent fixes

00:14✓format · lint · agent advances

00:47●klasp:test ✗ → test_total::charges_tax · agent investigates

01:22✓all gates · commit · open PR #142

01:25▸agent: implement refund handler

07:00✓4 clean PRs in your queue. All green CI. Ready to review.

01 — deterministic done

Exit codes are unambiguous. Agents stop guessing whether they're finished — the gate said zero, the gate said one. No drift, no panic loops.

02 — structured findings

When a gate fails, klasp surfaces line-numbered diagnostics from cargo, pytest, your linter — so the agent fixes the actual error, not a hallucinated symptom.

03 — bounded context

Tight pass / fail loops mean each iteration burns a few hundred tokens, not tens of thousands. Overnight runs stay inside their context window.

Why klasp

One config. Same gates. Both audiences.

01 Stop bad PRs at the source

Agents can't merge what they can't pass. klasp wires your existing fmt / lint / test commands into deterministic exit-code gates the agent has to clear before it commits.

02 One config, both audiences

klasp.toml is the single source of truth. The same gate that guards your pre-commit hook guards the agent loop — no second config to drift out of sync.

03 Three surfaces, plugin protocol for the rest

First-class for Claude Code, Codex CLI, and Aider. Managed .claude/settings.json / AGENTS.md / .aider.conf.yml blocks installed idempotently, with conflict detection and clean uninstall. New surfaces ship via the v0 plugin protocol — fork the reference plugin and you're done.

Recipes

Typed recipes for the gates you already run.

klasp.toml

# fmt — wraps an existing pre-commit hook
[[checks]]
name    = "format"
type    = "pre_commit"
hook_id = "rustfmt"

# lint — fallow groups multiple checks under one verdict
[[checks]]
name = "lint"
type = "fallow"

# test — pytest with JUnit-XML diagnostics surfaced to the agent
[[checks]]
name      = "test"
type      = "pytest"
junit_xml = true

# build — cargo with structured compiler diagnostics
[[checks]]
name       = "build"
type       = "cargo"
subcommand = "check"

For builders

A machine contract, not just a hook.

klasp is the deterministic adjudicator your orchestrator polls. klasp gate returns a versioned verdict — the same contract drives the agent surface, CI, plugins, and autonomous runs.

klasp gate --format json

$ klasp gate --format json
# exit 0 = pass · exit 2 = fail (block) · stable, versioned
{
  "output_schema_version": 1,
  "verdict": "fail",
  "checks": [
    {
      "name": "test",
      "verdict": "fail",
      "findings": [
        {
          "severity": "error",
          "file": "src/lib.rs",
          "line": 42,
          "rule": "test_total::charges_tax"
        }
      ]
    }
  ]
}

Structured output

JSON, plus --format junit and --format sarif — land agent verdicts in CI summaries and GitHub code-scanning. Schema →

Subprocess plugin protocol

JSON over stdin/stdout, --describe / --gate. Add a custom check or surface and klasp runs it. v0 protocol →

Orchestrator-ready v0.5.0

The klasp-plugin-agentic-flow reference gates push on .agentic-flow/ step receipts — resume from the earliest stale step. Reference plugin →

Parallel & fail-open

rayon work-stealing across checks; infra errors degrade to warn, never a spurious block. Protocol is experimental v0 — pin the schema, detect drift.

Agents

First-class support for the agents you ship with.

Capability	Claude Code	Codex CLI	Aider	Cursor
Pre-commit gate	✓	✓	✓	—
Push gate	✓	✓	—	—
Managed config	`.claude/settings.json`	`AGENTS.md`	`.aider.conf.yml`	—
Idempotent install / uninstall	✓	✓	✓	—
Conflict detection	✓	✓	—	—
Captured-session test	✓	✓	✓	—

Cursor's hook surface is still beta as of Cursor 3.3 with open correctness bugs — deferred to v0.3.x or v1.0. Need a different agent? Ship a plugin: two reference plugins now — pre-commit and agentic-flow — plus the v0 protocol spec.