TypeScript SDK

Advanced Usage

Real-world recipes that combine the SDK's primitives (webhooks, triage scripts, and on-demand agents).

The SDK is in early alpha. It is not meant for production use and may be removed in the future. Stay on the latest version (@orca_sh/sdk@latest) while we iterate.

End-to-end recipes to copy as starting points.

Sentry webhook → agent on the bug

When Sentry fires an alert, file a task and spawn an agent to investigate. In production, verify the Sentry signature header before trusting a payload. This example omits that check.

sentry-webhook.ts
import { Hono } from 'hono';
import Orca from '@orca_sh/sdk';

const app = new Hono();
const client = new Orca();
// reads ORCA_API_KEY + ORCA_ORGANIZATION_ID from env

const TARGET_HOST_ID = process.env.ORCA_TARGET_HOST_ID!;  // see hosts.list()
const PROJECT_ID = process.env.ORCA_PROJECT_ID!;          // see projects.list()

app.post('/webhooks/sentry', async (c) => {
  const event = await c.req.json();
  const { title, web_url: sentryUrl, culprit, short_id } = event.data.issue;
  const slug = `sentry-${short_id.toLowerCase()}`;

  // 1. File a task so the bug shows up in the dashboard
  const task = await client.tasks.create({
    title: `[Sentry] ${title}`,
    description: `Triggered by ${culprit}\n\nSentry: ${sentryUrl}`,
    priority: 'high',
    labels: ['sentry', 'bug'],
  });

  // 2. Create a worktree on a developer's machine and run an agent in it
  const result = await client.workspaces.create({
    hostId: TARGET_HOST_ID,
    projectId: PROJECT_ID,
    name: slug,
    branch: slug,
    agents: [
      {
        agent: 'claude',
        prompt: [
          `A Sentry alert just fired:`,
          `  Title: ${title}`,
          `  Culprit: ${culprit}`,
          `  URL: ${sentryUrl}`,
          ``,
          `Reproduce the failure, fix it, push a branch, and update task`,
          `${task.id} with what you found.`,
        ].join('\n'),
      },
    ],
  });

  return c.json({
    ok: true,
    taskId: task.id,
    workspaceId: result.workspace.id,
    sessionId: result.agents[0]?.ok ? result.agents[0].sessionId : null,
  });
});

export default app;

Result:

  • The task shows up in the dashboard for everyone.
  • The workspace is a real git worktree on the target machine. A human can take over if the agent gets stuck.
  • The agent runs in the new workspace with the prompt above, the codebase, and any MCP servers the host has configured.

To spawn several agents in parallel, add entries to agents:

agents: [
  { agent: 'claude', prompt: 'Reproduce the bug and write a failing test.' },
  { agent: 'claude', prompt: 'Investigate related Sentry issues from the last 7 days.' },
],

Burn down the P0 backlog overnight

Spawn an agent on every urgent task in parallel. Each agent pushes a branch and updates its task.

burn-p0s.ts
import Orca from '@orca_sh/sdk';

const client = new Orca();
const HOST_ID = process.env.ORCA_HOST_ID!;
const PROJECT_ID = process.env.ORCA_PROJECT_ID!; // see projects.list()

const p0s = await client.tasks.list({ priority: 'urgent', limit: 50 });

const dispatched = await Promise.all(
  p0s.map((task) =>
    client.workspaces.create({
      hostId: HOST_ID,
      projectId: PROJECT_ID,
      name: task.slug,
      branch: task.slug,
      agents: [
        {
          agent: 'claude',
          prompt: [
            `Pick up task ${task.slug}: "${task.title}".`,
            ``,
            task.description ?? '(no description; read recent changes for context)',
            ``,
            `Investigate, make the fix, run the relevant tests, push the branch, and`,
            `update task ${task.id} with a one-paragraph summary of what changed and why.`,
            `If you can't make confident progress in ~30 minutes, leave a comment with`,
            `where you got stuck and stop.`,
          ].join('\n'),
        },
      ],
    }),
  ),
);

console.log(`dispatched ${dispatched.length} agents across the P0 backlog`);

Run it from a daily cron on a powerful host. Fixed bugs get a PR-ready branch. Others get a comment explaining where the agent stopped.

Sweep a refactor across every repo

Use one loop for changes that must land the same way in many repos, such as an API rename, a dependency bump, or a lint rule rollout:

sweep-rename-getUser.ts
import Orca from '@orca_sh/sdk';

const client = new Orca();
const HOST_ID = process.env.ORCA_HOST_ID!;

const projects = await client.projects.list({ hostId: HOST_ID });

const wave = await Promise.all(
  projects.map((p) =>
    client.workspaces.create({
      hostId: HOST_ID,
      projectId: p.id,
      name: `rename-getUser-${p.name}`,
      branch: 'refactor/rename-getUser',
      agents: [
        {
          agent: 'claude',
          prompt: [
            `Rename every caller of \`getUser()\` to \`fetchUser()\` across this repo.`,
            ``,
            `1. Find call sites with grep.`,
            `2. Update each one and re-run the test suite.`,
            `3. If green, push the branch and open a draft PR titled`,
            `   "refactor: rename getUser → fetchUser".`,
            `4. If a repo doesn't actually use getUser, exit cleanly with a note.`,
          ].join('\n'),
        },
      ],
    }),
  ),
);

const totalAgents = wave.reduce(
  (n, result) => n + result.agents.filter((agent) => agent.ok).length,
  0,
);
console.log(`launched ${totalAgents} agents across ${projects.length} repos`);

The same loop works for "bump TypeScript to 5.7" or "add a lint:strict script to every package.json".

On-demand agent dispatch from your tools

Fire an existing automation off-schedule from anywhere, such as a Slack slash command, a CI job, or an admin panel:

const run = await client.automations.run('<automation-id>');
console.log(`dispatched run ${run.runId} for automation ${run.automationId}`);

The automation's pinned host must be online and tunneling. Otherwise the SDK throws a 503 Host not connected error.

On this page