What is SNA?

SNA (Skills-Native Application) is an SDK for building products on top of agent runtimes. Instead of calling an LLM API directly, your app talks to a small server that manages a long-lived Claude Code, Codex, or OpenCode process, and SNA gives you one canonical API for all three.

For the story behind why SNA started, see Origin.

The shape

your app
   │
   │  HTTP (request/response, ordering)
   │  WS   (live events, fanout)
   ▼
SNA server  ──spawn──►  claude-code | codex | opencode
   │
   ▼
SQLite (canonical history)

You start one server. You open one or more sessions. Each session spawns a real CLI binary (claude, codex, or opencode) as a managed subprocess. SNA normalizes every runtime's events, history, and permission model into one shape so the consumer app doesn't have to fork by runtime.

Terminology note: the public docs call Claude Code, Codex, and OpenCode runtimes. The API still uses field names such as provider, providerOptions, and modelProvider for compatibility with existing SDK callers.

What problem this solves

The official LLM APIs work fine for stateless completions, but the moment your product needs:

• A long-running agent with tools, file edits, and approvals: you end up reimplementing Claude Code or Codex's loop yourself.
• The same agent under different runtimes (Claude for code edits, Codex for image generation, OpenCode for cost): every switch is a rewrite of the integration.
• Conversation history that survives runtime swaps: the native formats don't interoperate, so you either pick one runtime for life or lose context on every switch.
• Permission flows that look the same to your users: Claude's PreToolUse hook and Codex's JSON-RPC approval speak different protocols and produce different UX.

SNA takes "use the actual CLI" as a serious answer to all of these. The CLIs already do the hard parts (tool dispatch, sandboxing, permission gating, history). SNA wraps them so a single consumer-side codebase works across all three.

Why not build it directly with model APIs?

Direct model APIs and vendor SDKs are the right layer for stateless model calls. They are not the same thing as an agent runtime. If you build directly on those APIs, your product owns the API keys, tool orchestration loop, approval UX, file-edit handling, streaming event shape, retries, and history format.

SNA takes a different route: it orchestrates the agentic CLI harness provided by each runtime. Those harnesses are already tuned by the companies building the models: how context is prepared, how tools are called, how permissions are requested, how sandbox boundaries are enforced, and how long-running work recovers. SNA keeps that harness in place and normalizes the app-facing API around it.

SNA still needs the underlying CLI to be installed and authenticated on the machine where it runs. The difference is that your product does not need to recreate every model vendor's agent harness from raw completion APIs.

What you get

• One canonical conversation model. Messages live as flat blocks with two orthogonal axes: actor (user/assistant/system) and kind (text/thinking/tool_use/tool_result/status/error). Runtime-native shapes are derived from this on demand. See Actor and kind for the design rationale.
• Session continuity without cache plumbing. The normal path is to keep the same SNA session and call agent.send for the next turn. SNA keeps the active runtime-native conversation/thread attached. If a process has to restart, it rebuilds from canonical history. Your app does not reload history, replay prompts, or configure cache keys just to continue a conversation.
• 3-layer attribution. Every block records provider (runtime), modelProvider (vendor), and model (slug). Swap any of them mid-session and the per-row truth stays honest.
• Unified event protocol. 15 normalized event types over WebSocket or SSE: assistant_delta, tool_use, permission_needed, complete, and friends.
• Unified permission flow. One API surfaces both Claude's PreToolUse hook and Codex's JSON-RPC approval. The consumer app's approval dialog doesn't change per runtime.
• Runtime control without restart. Change model, permission mode, or working directory mid-thread. Restart and resume rebuild runtime-native history from canonical blocks.
• First-class one-shot APIs. completion() and runOnce() skip the session machinery for short single-prompt jobs (autocomplete, chat naming) with optional streaming callbacks.

Who this is for

• Product builders layering a chat or copilot experience on top of an agent CLI. SNA is the integration boundary: your app does the UI, SNA does the runtime plumbing.
• Multi-runtime apps that want users to pick (or auto-route) between Claude Code, Codex, and OpenCode without forking the integration per runtime.
• Electron / desktop apps embedding an agent locally. The launcher forks the server as a managed child process, handles asar-unpacked paths, and locates native bindings.

What this is not

• Not a hosted LLM endpoint. SNA spawns the real CLIs on the host it runs on; you provide the binaries and credentials.
• Not an agent framework. It doesn't tell you how to build agents. That's what Claude Code / Codex / OpenCode do. SNA is the layer that lets your app drive them.
• Not a wrapper that hides the underlying CLI's behavior. When Claude Code edits a file, you see the real edit. When Codex generates an image, you get the real file path. SNA normalizes the shape, not the semantics.

If you are comparing SNA with Zed's Agent Client Protocol, see SNA and ACP.

Where to go next

Read the Quick Start for the 5-minute hands-on walkthrough (boot the server, open a session, send a prompt, watch events). After that, the Concepts tab covers the session model, canonical history, and runtimes in depth; API Spec is the on-the-wire reference.