snodo

Get evidence that an agent's work is done before it merges. Snodo runs your process validators and test gate inside the agent's own work loop.

The gate caught work an agent thought was ready: across 515 gate runs, 102 did not pass; in 15 tasks, the gate sent failing-test evidence back to the coder and the next attempt passed. See the examples and counts.

Install and first run

Follow the canonical per-language first-run quickstart for Python, Node/TypeScript, Go, or Rust. It includes the starter files needed for the initial commit, the Git identity prerequisite, and each stack's detected test command and governed hello-world mock task. Install or update Snodo with:

curl -fsSL https://snodo.dev/install | bash

The installer sets up uv if needed. Alternatives are uv tool install snodo and pip install snodo. To try the published package without installing it, run uvx snodo --version. Python 3.12+ is required.

Before spending anything on an existing repository, run snodo ready. Without an LLM, it checks whether the artefacts the protocol expects — decision records, a resolvable test command, coder configs — are committed, and scores what is missing by how cheap it is to fix. Task worktrees only see HEAD, so "present on disk" is not enough. See the runbook for readiness, the full configuration surface, and the command reference.

Why add this alongside CI, agent instructions, and code review?

Snodo enforces the protocol's validators and test gate before work merges, inside the agent's own loop. A failure returns to the coder as evidence; a blocker halts the run and cannot be outvoted; every decision is recorded in a hash-chained audit log. The cost is one gate run per task, plus the validators' model calls.

Built with snodo

From v0.19.0, snodo is developed with snodo. Each change to this repository starts as a task spec, passes snodo's validators, is written by a coding agent in its own worktree, is verified by the test gate, and arrives here as a pull request that snodo opened. The protocol that governs this repository is .snodo/protocol.yml, and every run is recorded in its audit log.

AI coding agents are fast, confident and non-deterministic. They will report a task as finished while a test is failing, while the change has drifted outside the task, or while it contradicts a decision your team recorded months ago. Asking the agent again does not settle any of that. snodo is built for the gap: you describe your development process as a protocol, and the engine enforces it around whichever agent writes the code.

The protocol is a YAML file. It declares modes — the stages of your process, each with an explicit tool set — validators that must agree before work proceeds, and the policy for when they disagree. Enforcement is structural, not advisory: mutations are gated behind a signed validation token, a single blocker halts execution before any vote (so a critical finding cannot be outvoted), and every governance decision is written to a hash-chained audit log. snodo does not make an agent more reliable. It makes the process hold whether or not the agent cooperates.

The working loop

Connect an agent to Snodo over MCP. Group work into plans. A plan is one clear intention. Waves group its tasks: tasks in a wave run in parallel, and waves run in series. Queues group and schedule plans. Dispatch a single task only for a true one-off with no related work. A plan with one task in one wave adds nothing. The orchestrator then validates and starts the work. Each task still passes through the protocol's validator loop; jobs run asynchronously. Follow task status and progress in the configured cloud live view (/now?task_ref=<task_ref>) when cloud sync is configured, and follow live output with snodo logs <job_id> --watch. watch_job also has an optional MCP Apps panel, but some hosts (including Claude Desktop and relayed sessions) show only its plain-text snapshot.

Register Snodo's mode-pinned MCP servers with snodo serve --mcp-install. Installation supports Claude Desktop, Claude Code, Cursor, Gemini CLI, GitHub Copilot (VS Code and CLI) and the Codex family (ChatGPT desktop, Codex CLI and IDE extension). It writes their user-level configurations: Claude Desktop's platform-specific config, Claude Code's ~/.claude.json, Cursor's ~/.cursor/mcp.json, Gemini CLI's ~/.gemini/settings.json, and Codex's ~/.codex/config.toml (relocated by CODEX_HOME). Only detected clients are updated; unrelated MCP entries are preserved and each updated client is reported. Restart each updated client to connect.

Optional job notifications can send project-named updates to ntfy, a generic webhook, Slack, Discord, or Teams. Configure targets in ~/.snodo/config.yml ($SNODO_HOME/config.yml when overridden), then check them with snodo config --notify-test. The configuration reference covers all user-level settings.

orchestrator → MCP validate/dispatch or plan/queue → job → live browser watch
                                                     └→ snodo logs <job_id> --watch

That makes snodo an AI-SDLC protocol engine: a governance layer over the software development lifecycle, for teams where AI agents are first-class contributors. The coder is interchangeable and separate from the judge — an in-process LLM client, a host CLI authenticated against your own subscription, or a containerised server all converge on the same gate and the same merge path.

Container image

Build the Snodo engine image from the repository root with docker build -f docker/Dockerfile -t snodo .. Run it against a mounted Git repository with docker run --rm -v "$PWD:/workspace" -w /workspace snodo ready; the image's entrypoint is snodo, so CLI arguments are passed directly. The image contains no code-host credentials; provide any required credentials through your runtime's normal environment or secret mechanism.

What a mock run does

The canonical quickstart's --mock run uses a deterministic stub coder that writes a stack-specific hello-world fixture and test; it implements the hello-world task. The task still passes through the configured governance and verification flow, and the generated test passes with that stack's test runner available. The mock makes no provider API call and does not prove that a real coder can implement your project's requirements. For provider-backed coding, configure credentials (for example, snodo config add anthropic <key> or ANTHROPIC_API_KEY) and run without --mock.

Project status

Actively-developed research implementation (beta). The enforcement invariants — token integrity, capability boundaries, non-overridable blockers, audit completeness — are verified by property-based tests over randomised inputs. Measured size, complexity and the CI gates are on the docs home.

Three honest boundaries, so you meet them here rather than an hour in:

• The opencode coder paths are experimental. litellm (the default), openai, anthropic, gemini, opencode-cli, codex-cli, claude-cli, agy and mock are supported. The built-in litellm coder exists so snodo works with nothing else installed; if an expert CLI is available, prefer it.
• The repository is trusted, not sandboxed. snodo runs your test and build commands, and a protocol file is executable input, like a Makefile or a CI config. ADR 014 is the threat model; do not point it at untrusted code.
• This is a preprint-stage research artifact. The paper is under review; treat the code as a working implementation of the ideas, not a finished product.

Where to go next

Research

Preprint: Specifying AI-SDLC Processes: A Protocol Language for Human-Agent Boundaries — arXiv:2606.20615.

Prifti, Y. (2026). Specifying AI-SDLC Processes: A Protocol Language for Human-Agent Boundaries. arXiv:2606.20615. https://doi.org/10.48550/arXiv.2606.20615

@misc{prifti2026snodo,
  title         = {Specifying AI-SDLC Processes: A Protocol Language for Human-Agent Boundaries},
  author        = {Prifti, Ylli},
  year          = {2026},
  eprint        = {2606.20615},
  archivePrefix = {arXiv},
  doi           = {10.48550/arXiv.2606.20615},
  url           = {https://arxiv.org/abs/2606.20615}
}

Empirical studies live in studies/, and the paper's claims are mapped to code and tests in Research.

Contributing

See CONTRIBUTING.md.

License

Copyright (C) 2026 The snodo Authors. Licensed under the Apache License, Version 2.0 — see LICENSE.