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 a live job with the browser watch link returned when an HTTP/tunnel URL is configured, or 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 and the Codex family: ChatGPT desktop, Codex CLI, and the IDE extension share ~/.codex/config.toml (relocated by CODEX_HOME). Only clients with an existing config directory are updated; 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

pip install snodo
snodo init --template solo
snodo config add anthropic sk-ant-...
snodo run "add a hello() function that returns the string 'world', with a test"

Python 3.12+. A key already exported in your environment (ANTHROPIC_API_KEY and friends) is auto-detected. snodo run ... --mock needs no key and no network at all.

Make an initial commit before the first run: each task executes in a git worktree on a branch off HEAD, and on a repository with no commits snodo refuses to run rather than silently dropping isolation (ADR 025).

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 run looks like

A project initialised from the solo template with its test command declared (--test-command "python -m pytest -q"), then:

$ snodo run "add a hello() function that returns the string 'world', with a test" --mock

✓ Loaded protocol: Solo Developer Protocol
  Validators: security, architecture, quality, meta-spec, acceptance
  Policy: unanimous

  Validating (pre-execute): security, architecture, meta-spec
    meta-spec: finished
    architecture: finished
    security: finished
  Coder dispatched
  Coder returned (3 artifact(s))
  Post-validating: quality, acceptance
    acceptance: finished
    quality: finished
✓ Verified merge for task/task_ca8fd940fe5d/add-a-hello-function-that: task
  task_ca8fd940fe5d verified at commit 3e144ca (python -m pytest -q).

task_ca8fd940fe5d  resolved  (depth=0)

--mock swaps in a deterministic stub coder, so no key is spent and no network call is made. The gates are not stubbed: the post-execute quality validator ran this project's declared test command (python -m pytest -q) against the change and passed it. Replace --mock with a configured provider or --coder opencode-cli and the same gates judge the real change. The transcript is trimmed for length; the protocol language is in the protocol reference and the coder backends are in Coder backends.

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.