User Guide

1. Installation

Linux / macOS — one command (recommended)

curl -fsSL https://synoema.tech/install.sh | sh

The script detects your platform, downloads and SHA256-verifies the binary, installs to ~/.sno/bin/, adds it to PATH, and runs sno doctor.

Windows

iwr -useb https://synoema.tech/install.ps1 | iex

From source (requires Rust ≥1.75)

git clone https://github.com/Delimitter/synoema
cd synoema/lang
cargo install --path crates/synoema-repl

MCP server without Rust (npx)

npx synoema-mcp

Requires Node.js ≥16. Downloads the binary automatically on first run.

Verify the installation

sno eval "6 * 7"   # → 42
sno doctor          # check PATH, GBNF, version

If you see 42 — you’re ready.

2. First Program

Create a file hello.sno

-- hello.sno
-- Comments start with --

-- Function: name arguments = body
greet name = "Hello, ${name}!"   -- ${} for interpolation

-- main = program entry point
main = print (greet "World")

Run it

sno run hello.sno
# Hello, World!

REPL for quick experiments

sno              # start interactive REPL
# > 2 + 2
# 4
# > map (\x -> x * x) [1..5]
# [1 4 9 16 25]
# Exit: Ctrl+D

Evaluate an expression directly

sno eval "[1..10] |> filter (\x -> x % 2 == 0) |> sum"
# 30

3. Syntax in 5 Minutes

Functions

-- No def, no return
double x = x * 2
add x y  = x + y

-- Multiple equations = pattern matching
fac 0 = 1
fac n = n * fac (n - 1)

-- Local variables via indentation
circleArea r =
  pi_val = 3.14159    -- local binding
  pi_val * r * r      -- result

Conditionals: ? ... -> ... : ...

abs x = ? x >= 0 -> x : -x

-- Chained conditions
grade score =
  ? score >= 90 -> "A"
  : ? score >= 80 -> "B"
  : "C"

Lists (no commas!)

nums  = [1 2 3 4 5]
range = [1..10]
map (\x -> x * 2) nums    -- [2 4 6 8 10]
filter (\x -> x > 3) nums -- [4 5]

Strings and interpolation

name = "Synoema"
s    = "Hello, ${name}!"        -- "Hello, Synoema!"
-- Concatenation: ++ (not +)
full = "Hello" ++ ", " ++ "World"

Types are inferred automatically

-- Annotations are optional (useful as documentation)
add : Int -> Int -> Int
add x y = x + y

-- Hindley-Milner: compiler infers all types
-- Write something wrong and the compiler explains the error

4. Creating a Project

sno new myapp                          # create project
sno new mylib --template library       # library
sno new mytool --template mcp-tool     # MCP tool
sno new myapp --template cli-app       # CLI app

Creates a directory with this structure:

myapp/
  main.sno        -- entry point
  sno.toml        -- project configuration

cd myapp
sno run main.sno  -- run the project

5. MCP Setup for Claude

The Synoema MCP server lets Claude Desktop and Cursor run and typecheck Synoema code directly from the chat.

Automatic setup (recommended)

sno setup claude    # configure Claude Desktop
sno setup cursor    # configure Cursor
sno setup all       # both

Manual setup — Claude Desktop

Open the configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "synoema": {
      "command": "npx",
      "args": ["synoema-mcp@0.1.0-beta.1"]
    }
  }
}

Restart Claude Desktop. Synoema tools will appear in the chat: typecheck, run, doc_query.

Manual setup — Cursor

Open ~/.cursor/mcp.json:

{
  "mcpServers": {
    "synoema": {
      "command": "npx",
      "args": ["synoema-mcp@0.1.0-beta.1"]
    }
  }
}

Local binary instead of npx

sno mcp-install             # install MCP server locally
sno setup claude --binary   # point config to local binary

6. RAG — Context-Aware Code Generation

RAG (Retrieval-Augmented Generation) gives LLMs access to Synoema corpus examples, documentation, and skill definitions at generation time — so the model has concrete working code to reference, not just training weights.

Step 1: Install the RAG pack

sno rag install          # download index.bin + ONNX embedder (~250 MB)
sno rag status           # confirm: index loaded, model ready

Run once. The pack is SHA-256-verified and versioned. After installation, all three integration modes below become available.

Mode A — Auto-inject (small LLMs ≤32B, transparent)

The MCP server automatically appends relevant corpus snippets to every typecheck, run, and feedback_loop tool response. No LLM reconfiguration needed — the model simply sees more context.

# Enable in ~/.sno/config.toml
[rag.auto_inject]
enabled = true

# Or let setup write the config for you
sno setup claude --with-rag
sno setup cursor --with-rag

The LLM receives a retrieval_context field with the top-3 matching examples appended to every tool response automatically.

Mode B — Explicit search tools (large LLMs — Claude, GPT-4)

Large LLMs can call RAG retrieval tools directly via MCP. Five tools are available in the chat:

The LLM decides when to call these tools based on the query. No user action required after MCP setup.

Mode C — sno fix --with-rag (CLI auto-fix loop)

Combines the inline ReAct fix agent with retrieval. The agent runs Thought → Action → Observation cycles and can search the corpus and docs before each fix attempt:

sno fix broken.sno --with-rag             # top-3 hits per action
sno fix broken.sno --with-rag --top-k 5  # retrieve more context

RAG command reference

7. Local Models via Ollama

Run fine-tuned Synoema code-generation models entirely offline — no API key required.

Install a model

# Pull directly from HuggingFace (Ollama ≥ 0.3)
ollama run hf.co/delimitter/synoema-coder-3b-v3:Q4_K_M

# Or use a Modelfile with the system prompt locked in:
cat > Modelfile << 'EOF'
FROM hf.co/delimitter/synoema-coder-3b-v3:Q4_K_M
SYSTEM "You are a Synoema code generator. Output only valid Synoema source code, no explanation."
EOF
ollama create synoema-coder-3b -f Modelfile
ollama run synoema-coder-3b

Available models

* compile_pass on IoT rule test set

Generate and verify

# Generate code
ollama run synoema-coder-3b "Compute GCD of 48 and 18" > result.sno

# Verify with Synoema
sno check result.sno
sno run result.sno

REST API

curl http://localhost:11434/api/generate \
  -d '{
    "model": "synoema-coder-3b",
    "prompt": "Filter even numbers from [1..20] and sum them",
    "stream": false,
    "options": { "temperature": 0 }
  }' | jq -r '.response'

→ Full Ollama documentation

8. Useful Commands

9. Where to Go Next