s0ma

Your AI doesn't know what you know about your code: why each part exists, what it promises, and what it must never do. So you explain it again every session, or it guesses.

s0ma is an open-source language for building software that explains itself to you and your AI. It moves that knowledge into the code, where the build holds it true, so you, your coding agent, and the AI running your application all read the same account. s0ma contains no AI model and needs none.

What you get

How it works

You write .s0ma files. Each part opens with a declaration of what it is for, what it expects, what it guarantees, and what it must never do, followed by a line of three hyphens and then ordinary Python:

nerve greet :: DOMAIN
    kind: FUNCTION
    visibility: PUBLIC
    intent: "Return a greeting for the name it is given."
    expects: "A name, as text."
    guarantees: "Returns a greeting that contains the name."
    forbids: none
    ...
    ---
    def greet(name: str) -> str:
        """Return a greeting for the name it is given."""
        return f"Hello, {name}!"

The ... stands for twelve more lines, nearly all of them none, so that an unanswered question never looks like an answer of nothing. Your first project has the whole file, and the quick reference has every line a declaration can carry.

s0ma build turns the source into plain Python and writes beside it a machine-readable record of everything declared, which we call the self-model. Because a part has to be declared to exist, that record can't drift from the code without something refusing to build. The vocabulary comes from the nervous system, since s0ma connects a brain, such as a language model, to the body of software it acts on.

Word What it is
nerve A working part: a function, a class, or a service.
cell Where data lives.
ganglion A part that watches and responds.
axon A declared dependency between two parts.

How agents meet it

An agent building a s0ma application works through the s0ma command line or the authoring MCP server, and the guardrails refuse an undeclared or drifted change before a person sees it. When the application runs, it loads the self-context every build emits and hands it to the agent operating it, as quoted project data rather than instructions.

Is it for you?

It probably fits if:

It probably doesn't if:

The last of these is the whole mechanism, and without it s0ma is overhead.

s0ma doesn't replace your tests or your production monitoring. It tells you what the system is, but not whether it is working.

Get it

The code is in the public repository at github.com/kn0w-thyself/s0ma, with the install steps kept in one place in its README. Getting started takes you through a first project, and if you already have a working application, retrofitting an existing codebase converts it a module at a time with the code working at every step.

Questions and bug reports are welcome in the repository's issues and discussions, or by email at hello@kn0wthyself.ai.