snodo

Enforce your development process around whichever AI agent writes the code.

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

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. Try the published package without installing it with uvx snodo --version, or install it for regular use with uv tool install snodo; pip install snodo is also available as a fallback. Python 3.12+ is required.

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.

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.

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), 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.