doloop CLI

The deterministic convention gate for AI-written code. It reads your codebase, infers the conventions it already holds (the ones kept in at least 70% of the places they apply), and flags a change that breaks them, with the rule, the line, and the rate behind every call. Same input, same verdict, every run.

Architecture & schema: this README documents the gate/selftest/MCP surface. For the whole Code product — the read cockpit, the five lenses, the data/blob schema, and how the gate and the read service share one engine — see code-page/ARCHITECTURE.md and code-page/SCHEMA.md.

Full command surface

Two ways to run it. Pick your privacy posture.

1. Local (default) — your source never leaves your machine

The engine runs on your machine. We ship it as a sealed binary, so your code stays put and the engine is not readable. This is the recommended mode and the one the pre-commit hook and CI action use.

pip install doloopio
doloop gate --staged             # gate your staged change before commit
doloop gate path/to/file.py      # gate one file against the codebase
doloop selftest                  # PROVE byte-identical determinism + see the tier-labeled lens roster

Exit code is 0 on pass and 1 on a flagged break, so it drops into a gate:

doloop gate --staged && git commit

2. Hosted (--hosted) — for teams that cannot run a binary

You send only the changed code to api.doloop.io over TLS. It is processed and not stored. Use this when a sealed binary is not an option in your environment.

export DOLOOP_KEY=dlp_...         # from https://api.doloop.io/dashboard
doloop gate --hosted --staged

Honest difference: local keeps your source on your machine; hosted sends the changed code to us (not stored). Same verdict either way.

Pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/ekras-doloop/doloop-cli
    rev: v0.1.0
    hooks:
      - id: doloop-gate

CI

Drop ci/doloop-gate.yml into .github/workflows/. It installs the sealed package on the runner and fails the check on a convention break.

For your coding agent (MCP)

Let the model gate its own output before it proposes a commit. The MCP server exposes the same local gate as a tool your agent can call, so the agent checks itself against an adversary that read the whole codebase, before the diff ever reaches a human.

pip install mcp

// .mcp.json (or ~/.claude/mcp.json for global)
{
  "mcpServers": {
    "doloop": { "command": "python3", "args": ["/path/to/doloop_mcp.py"] }
  }
}

Tools: doloop_gate(code, codebase, filename) gates a snippet, doloop_gate_staged(codebase) gates the staged change, doloop_version(). Runs local, source stays on the machine. The agent gets a PASS or FLAGGED verdict with the rule and the line behind any flag.

What it is, honestly

It gates fit, not correctness — it is not a bug oracle. Below the 70% inference floor it owes silence, so a messy or brand-new codebase can be quiet at first. Safety regressions block; local style only warns.

The verdict carries a reliability tier, and never borrows another tier's promise:

• mechanical (most lenses) — byte-identical, model-independent, forever. Run doloop selftest to prove it.
• execution (reverse-classical test quality, opt-in DOLOOP_CHECK_TESTS) — deterministic given a runnable test env; degrades loudly ("test quality NOT verified") when it can't run, never a silent pass.
• caged reader (semantic judgments, bring-your-own model) — reproducible per inferred convention, not byte-identical-forever.

Measured this build on public OSS (a proxy floor, not a per-customer guarantee): byte-identical across hash seeds; ~0.34% per-function false-block floor on accepted code across 1487 functions / 9 repos, 6 of 9 at exactly 0.0% (an upper bound — the residual is the legitimate-swallow judgment-call tail, surfaced for review, not bugs); 0 crashes. The per-customer false-block rate and velocity uplift come from a real team on real code, not from a corpus.

Suppressing a flag is a human review decision: doloop suppress <key> --note "why" records a reason and an author, expires (default 90 days), and is append-only in .doloop/ratchet.log. It is not a way for a tool or an agent to silence the gate mid-task. The method and its evidence: https://doloop.io/paper/

For maintainers: building the sealed engine

The public wheel ships the engine only as the compiled, non-readable module doloop_cli/_engine. The engine source is never in the distribution.

ENGINE_SRC=/path/to/engine/gate.py ./build_sealed.sh   # nuitka (preferred) or cython
python3 -m build --wheel                                # ships _engine.*.so, not source

In a dev checkout (no sealed build), point the CLI at the engine source:

DOLOOP_ENGINE_PATH=/path/to/engine python3 -m doloop_cli gate --staged