extension-authoring

Build a SynapsCLI Extension

Source of truth: {baseDir}/../../../docs/extensions/tutorial.md Read that file for the complete worked example. This skill is a structured summary + checklist you can keep in context while authoring.

---

What you are building

A separate process SynapsCLI spawns and talks to over stdin/stdout using JSON-RPC 2.0 with Content-Length framing. The runtime calls methods on you; you only respond. Any language works — Python 3 (no deps) is the tutorial language.

Two capabilities:

• Tool — callable by the model (tools.register permission required).
• Hook — reacts to lifecycle events, optionally blocks/modifies them (hook.* permission required per hook type).

---

Step 1 — Manifest (plugin.json)

Create .synaps-plugin/plugin.json in your extension root:

{
  "name": "hello-ext",
  "version": "0.1.0",
  "description": "Hello-world extension",
  "extension": {
    "entry_point": "python3 main.py",
    "extension_protocol_version": 1,
    "permissions": [
      "tools.register",
      "hooks.before_tool_call"
    ]
  }
}

Key fields:

• entry_point — shell command to start your process (resolved from plugin root).
• extension_protocol_version — must be 1.
• permissions — declare every capability you use; undeclared calls are rejected.

---

Step 2 — Framing helpers

Every message is a Content-Length: N\r\n\r\n header followed by N bytes of JSON. Write helpers once:

import sys, json

def send(obj):
    body = json.dumps(obj).encode()
    sys.stdout.buffer.write(b"Content-Length: " + str(len(body)).encode() + b"\r\n\r\n" + body)
    sys.stdout.buffer.flush()

def recv():
    header = b""
    while not header.endswith(b"\r\n\r\n"):
        header += sys.stdin.buffer.read(1)
    n = int(header.split(b"Content-Length:")[1].strip().split()[0])
    return json.loads(sys.stdin.buffer.read(n))

---

Step 3 — Handshake (initialize)

The runtime sends initialize first. You must respond with your capabilities: