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
echo '.agent-runs/' >> .gitignore

ckdn checks                    # list configured checks
ckdn run ruff                  # one atomic check → compact digest on stdout
ckdn run lint                  # alias → members (e.g. ruff, pylint)
ckdn show                      # pretty-print latest digest

ckdn run exits with the original command’s code, 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.

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