@pragma-sh/sdk

A typed TypeScript client for a running Pragma host — sessions, agent events, fanouts, scratchpads, whiteboards, and the workspace.

@pragma-sh/sdk is a TypeScript client for the Pragma gateway — the HTTP/JSON surface a running host exposes. The mobile app, the browser build, and agent plugins all speak through it; anything you build can too.

import { PragmaClient } from "@pragma-sh/sdk";

const client = new PragmaClient(); // config from the environment

for await (const event of client.workspace.subscribe()) {
  console.log(event.snapshot?.projects.length, "projects");
}

What it does

Getting started

Construct the client, configure the gateway, and handle errors.

Sessions

Spawn, attach, write to, resize, and kill terminal sessions — with scrollback replay.

Agents

Report status, ask questions, request approvals, and await the answers.

Fanouts

Create, watch, message, retry, cancel, and pick fanouts programmatically.

Scratchpads

Read, comment on, and send prompts through agent-authored MDX documents.

Whiteboards

Create, search, edit, and render durable Excalidraw boards.

Workspace & more

fs, git, exec, events, theme, push, and asset namespaces.

Design notes

Fetch-based, streaming with NDJSON. Subscriptions and session event streams are newline-delimited JSON over fetch + ReadableStream — no sockets, no SSE, so it runs in Node, Bun, React Native (the mobile client uses it), and browsers.
Dual ESM/CJS with .d.ts, built with bunup. Types for every wire shape (Fanout, KanbanPromptCard, …) are re-exported from @pragma-sh/constants, so TS and Rust agree by construction.
Typed errors. PragmaGatewayError (the gateway answered with a code and details) vs PragmaTransportError (network, config, or non-JSON response).
The gateway is the only transport. The SDK never talks to the Unix socket directly and never shells out to pragma-cli — that is the CLI's job.

Agents inside Pragma terminals

If your code runs in a Pragma terminal, the environment is already configured (PRAGMA_GATEWAY_URL, PRAGMA_GATEWAY_TOKEN, PRAGMA_TAB_ID, PRAGMA_WORKTREE_ID) — construct the client with no arguments.