quickstart: SDK

use the SDK when a workflow needs real control flow: branching, retries, fan-out over a computed list, or a schedule. orcr scaffold sets up a ready-to-run TypeScript project so you do not chain --json and jq in bash.

scaffold and run

orcr scaffold my-workflow && cd my-workflow
npx tsx workflow.ts

orcr scaffold creates the directory (if missing), writes exactly three files, and runs npm install. it never overwrites: if any of the three files already exists it fails with state_conflict and touches nothing. it is the one orcr command that does not talk to the server; the project it generates does, like any SDK client.

the three generated files

package.json    @orchestratr/sdk (pinned to this CLI's version) · tsx · typescript
tsconfig.json   ES2022 modules, strict mode, node types
workflow.ts     a runnable scope -> run -> wait -> last-response example

package.json pins @orchestratr/sdk to the exact version of the orcr CLI that scaffolded it, so the SDK and the socket protocol stay in step. the socket version check catches any drift loudly at runtime.

the generated workflow.ts is a working starting point:

import { orcr } from "@orchestratr/sdk";

// A minimal, runnable orchestration. For the full SDK surface (collections, scopes,
// watch, loops, the file convention) read the skill reference: skill/references/sdk.md
await orcr.scope("scaffold_demo", async () => {
  const a = await orcr.agent.run({
    // agent: "claude",           // optional: omitted here, so it uses config defaults.agent
    name: "hello",                // naming is mandatory: pass name OR path
    gc: "immediate",              // one-shot: settles on ended(completed)
    prompt: "Reply with a single friendly sentence, then say DONE.",
  });
  await a.wait();
  console.log(await a.lastResponse());
});

the shape: scope, run, wait, lastResponse

the SDK is a typed client of the socket API. anything the CLI can do, the SDK can do. orcr.agent.run returns a handle immediately, mirroring orcr agent run:

import { orcr } from "@orchestratr/sdk";

await orcr.scope("review", async () => {
  const a = await orcr.agent.run({
    agent: "codex",
    name: "reviewer",             // --name OR path: exactly one
    prompt: "Review src/auth.ts for auth bugs. Say DONE.",
  });

  a.uuid;                         // permanent id
  a.path;                         // "review/reviewer"
  a.dataDir;                      // this agent's data directory

  await a.wait();                 // settles: turn complete | blocked | ended
  console.log(await a.lastResponse());   // throws TranscriptUnavailable if none
  await a.kill();
});

orcr.scope(name, fn) prefixes every relative path created or targeted inside fn. a leading / on a path escapes the scope to the root. scopes nest, and the prefixes stack.

for a single request and answer, use the ask one-liner, which is sugar for a gc: "immediate" run, then wait, then lastResponse:

const answer: string = await orcr.ask({
  agent: "claude",
  name: "quick_check",
  prompt: "Is src/auth.ts safe against replay? One paragraph.",
});

failures become typed errors carrying { code, message, details }, one class per protocol error code: NotFound, InvalidRequest, StateConflict, Blocked, Timeout, IntegrationMissing, TranscriptUnavailable, EnvironmentError, ServerError. the SDK never prompts; destructive helpers behave like non-interactive CLI calls.

a plain npm project

add any dependency the workflow needs, and a human can review the code like any other code:

npm install @octokit/rest    # a GitHub client, a CSV parser, whatever the task needs

add more .ts files freely and run each with npx tsx <file>.ts.

next steps

• your first workflow turns this into a parallel code review.
• the data and file conventions explain how to get structured output from agents.