ckdn 1.3.3

Deterministic check runner and log digester for AI-assisted development loops

Let agents move fast.
Keep verification explicit, bounded, and machine-readable.

ckdn (short for checkdown) sits between a coding agent and your project’s verification tools. The agent never reads a 10 000-line pytest log and never decides from prose whether a run “looks green”.

Every check goes through one orchestrator that:

1. owns the true process exit code,
2. archives the full log as evidence,
3. emits a bounded, machine-readable digest — the only thing the agent is supposed to read.

Text-based interpretation of tool output fails two ways: context bloat (the agent drowns in a thousand-line log) and false green (a collection error prints no FAILED lines, so a regex calls it clean). ckdn's answer is a strict status model from both the exit code and a format-aware parser: the two must agree before anything is called green. ckdn may downgrade green; it never upgrades red.

Runtime: Python ≥ 3.11, stdlib only for the core CLI (zero third-party dependencies). The optional MCP server is an extra (ckdn[mcp]).

Install

uv tool install ckdn          # global CLI
# or as a project dev dependency:
uv add --dev ckdn

Quick start

cd your-project
ckdn init                      # writes starter ckdn.toml
# edit commands / parsers / aliases to match the project
echo '.agent-runs/' >> .gitignore

ckdn checks                    # list configured checks
ckdn doctor                    # pre-flight: tools on PATH, commands fit parsers
ckdn run ruff                  # one atomic check → compact digest on stdout
ckdn run lint                  # alias → its members in order
ckdn run --all                 # every atomic check → one aggregate
ckdn show                      # pretty-print the latest run's digest

The starter config enables checks a given project may not have (coverage, mypy, pre_commit, …); trim it first, or --all reports them as error.

ckdn run passes the original command’s nonzero exit code through, so it slots into any hook or CI step where the raw command used to be — with a bounded, schema-backed digest as a side effect. The one exception is the point of the tool: a command that exits 0 on a non-green digest exits 1. A code outside 1–255 (a signal death) becomes 1, not the nearest bound.

Documentation

Full documentation lives at orenlab.github.io/ckdn:

• Get started — install and first check
• Status model — exit code × parser → one verdict; exit-code contract
• Digests & schemas — the machine-readable contract (ckdn.digest/2)
• Aliases & aggregates — grouped checks and routing
• Baselines — gate CI on new findings only
• Configuration — ckdn.toml, command policy, working directory
• CLI — command reference
• Parsers — built-ins, custom parsers, and plugins
• Agents & MCP — wiring ckdn into an agent loop
• Design & non-goals

License & community

• Copyright (c) 2026 Den Rozhnovskiy <rozhnovskiydenis@gmail.com>
• License: MIT (SPDX-License-Identifier: MIT)
• Changelog: CHANGELOG.md
• Security: SECURITY.md
• Contributing: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md