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. The orchestrator chooses the smallest structure that fits—one task, a parallel wave, a multi-wave plan, or a queue of plans—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 first-run quickstart. It includes the starter file needed for the initial commit, the Git identity prerequisite, and the same governed hello-world mock task shown in the docs. 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.

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 src/hello.py and tests/test_hello.py; it implements the hello-world task. The task still passes through the configured governance and verification flow; with pytest installed and configured, the generated test passes. 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.