Skip to main content

Documentation Index

Fetch the complete documentation index at: https://bastani.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

@bastani/atomic-sdk/workflows is a library of pure primitives — there’s no wrapper to opt into. You compose the primitives into whatever CLI shape you want (Commander, citty, yargs, an OpenTUI app, anything else). Both the atomic CLI and your own worker files call the same primitives underneath.

​
Install

bun init -y
bun add @bastani/atomic-sdk
bun add @anthropic-ai/claude-agent-sdk     # the provider SDK you target
The SDK runs on Bun, not Node.js. You also need a multiplexer (tmux on macOS/Linux, psmux on Windows) and at least one authenticated agent CLI (claude, opencode, or copilot). See installation. The SDK is fully standalone — it bundles its own orchestrator dispatcher and never reaches into a sibling @bastani/atomic package.

​
Primitives

PrimitivePurpose
defineWorkflowAuthor a workflow with .for(agent).run(...).compile(). Pass source: import.meta.path for dispatch.
createRegistryBuild an immutable registry of workflows for iteration / lookup.
listWorkflows(reg)Snapshot every workflow in a registry.
getWorkflow(reg, …)Resolve (agent, name) → workflow.
getName / getAgent / getInputSchema / getDescription / getSource / getMinSDKVersionRead workflow metadata.
validateInputs(wf, raw)Run the same validation pipeline atomic uses (required, defaults, enum, integer).
runWorkflow({ workflow, inputs, detach?, pathToAtomicExecutable? })Spawn the orchestrator session and (optionally) attach. Resolves with { id, tmuxSessionName }.
hostLocalWorkflows(workflows, options?)Make your CLI dispatchable by the atomic binary. See host-local-workflows.
listSessions / getSession / stopSession / attachSession / detachSessionManage running sessions on the shared atomic socket.
getSessionStatus / getSessionTranscriptRead the orchestrator-written status snapshot or per-session messages from disk.
nextWindow / previousWindow / gotoOrchestratorPane navigation — pure tmux verbs that update the session’s current-window pointer.
MissingDependencyError / SessionNotFoundError / WorkflowNotCompiledError / InvalidWorkflowError / IncompatibleSDKErrorTyped errors thrown by the primitives above. Catch with instanceof for friendly CLI output.

​
Stage API

Inside a .run(async ctx => { ... }):
  • ctx.inputs — typed inputs (only declared field names are valid keys).
  • ctx.agent — "claude" | "copilot" | "opencode".
  • ctx.stage(opts, clientOpts, sessionOpts, fn) — spawn a session; returns a SessionHandle<T> with name, id, result.
  • ctx.transcript(ref) — { path, content } from a completed session.
  • ctx.getMessages(ref) — raw native messages from a completed session.
Inside a stage callback async s => { ... }:
  • s.client, s.session — pre-created provider client and session.
  • s.sessionId, s.paneId, s.sessionDir — identifiers and on-disk paths.
  • s.save(messages) — persist this session’s output for later stages.
  • s.transcript(ref) / s.getMessages(ref) — read upstream output.
  • s.stage(opts, clientOpts, sessionOpts, fn) — spawn a nested sub-session.
  • headless: true in stage options — run in-process without a tmux window.
See stages for the full callback surface.

​
Where to go next

defineWorkflow

The builder chain — name, agent, run, compile.

Stages

ctx.stage, parallel fan-out, transcript hand-offs, headless stages.

Inputs

Declared input schemas and validation.

runWorkflow

The composition root pattern and embedding under a parent CLI.

Embedding

Building your own atomic-powered app — registries, multi-workflow, embedding.

Picker

WorkflowPicker — the interactive picker as a reusable component.