SDK

Embed omp in your applicationCopy Anchor Link

Use the SDK when your host is written in TypeScript or JavaScript, runs on Bun, and should share a process with omp. You get the same agent core as the CLI, but your application owns the prompt lifecycle, receives streaming events, and can expose ordinary functions as agent tools.

For a different language, process isolation, or a stable JSON boundary, choose RPC mode instead.

bun add @oh-my-pi/pi-coding-agent

import { createAgentSession } from "@oh-my-pi/pi-coding-agent";

const { session, modelFallbackMessage } = await createAgentSession({
  cwd: process.cwd(),
});

if (modelFallbackMessage) {
  process.stderr.write(`${modelFallbackMessage}\n`);
}

const unsubscribe = session.subscribe((event) => {
  if (
    event.type === "message_update" &&
    event.assistantMessageEvent.type === "text_delta"
  ) {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

try {
  await session.prompt("Summarize this repository in three bullets.");
  process.stdout.write("\n");
} finally {
  unsubscribe();
  await session.dispose();
}

bun run embed.ts

Defaults and configurationCopy Anchor Link

createAgentSession() follows an “omit to discover, provide to override” model. With no options it discovers your omp credentials, settings, model, extensions, skills, rules, project context, prompt templates, slash commands, MCP servers, and tools. MCP and LSP integration are enabled by default.

This makes the smallest example useful in an existing omp setup. Embedders commonly override only the pieces they need to own:

Ephemeral and persistent sessionsCopy Anchor Link

The default session manager writes history to omp's session store. Use an in-memory manager for request-scoped jobs:

import {
  createAgentSession,
  SessionManager,
} from "@oh-my-pi/pi-coding-agent";

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
});

For an explicit file-backed session, use SessionManager.create(cwd). The same public class also provides continueRecent(cwd), list(cwd), open(path), and fork helpers; see Sessions.

Own model and settings selectionCopy Anchor Link

Use the package-root exports when the host must control credentials, model selection, and settings rather than relying on discovery:

import {
  createAgentSession,
  discoverAuthStorage,
  ModelRegistry,
  SessionManager,
  Settings,
} from "@oh-my-pi/pi-coding-agent";

const authStorage = await discoverAuthStorage();
const modelRegistry = new ModelRegistry(authStorage);
await modelRegistry.refresh();

const model = modelRegistry.getAvailable()[0];
if (!model) {
  throw new Error("No authenticated model is available");
}

const settings = Settings.isolated({
  "compaction.enabled": true,
  "retry.enabled": true,
});

const { session } = await createAgentSession({
  authStorage,
  modelRegistry,
  model,
  settings,
  sessionManager: SessionManager.inMemory(),
  enableMCP: false,
});

When you pass both authStorage and modelRegistry, the registry must have been created with that same auth-storage instance. For normal persisted configuration and its precedence rules, see Settings.

The default process-wide AgentRegistry admits one top-level Main identity per generation. If your application runs multiple independent top-level sessions concurrently, give each session its own agentRegistry: new AgentRegistry().

Stream events into your hostCopy Anchor Link

session.subscribe(listener) returns an unsubscribe function. The most useful public events are:

Event listeners are notifications, not a backpressure mechanism: the session does not await an async listener. Queue expensive host work yourself if ordering matters.

Add a host-owned toolCopy Anchor Link

A CustomTool is a public callback contract. Define its input with the package's exported z schema builder and return text or image content for the model. The final AbortSignal lets session cancellation reach your I/O.

import {
  createAgentSession,
  type CustomTool,
  z,
} from "@oh-my-pi/pi-coding-agent";

const lookupTicket: CustomTool = {
  name: "lookup_ticket",
  label: "Lookup ticket",
  description: "Fetch a support ticket by its public ticket ID.",
  parameters: z.object({ ticketId: z.string() }),

  async execute(_toolCallId, { ticketId }, _onUpdate, _context, signal) {
    try {
      const response = await fetch(
        `https://support.example.test/tickets/${encodeURIComponent(ticketId)}`,
        { signal },
      );

      if (!response.ok) {
        return {
          content: [{ type: "text", text: `Ticket lookup failed (${response.status}).` }],
          isError: true,
        };
      }

      const ticket = await response.json();
      return {
        content: [{ type: "text", text: JSON.stringify(ticket) }],
      };
    } catch (error) {
      if (signal?.aborted) throw error;
      return {
        content: [{ type: "text", text: `Ticket lookup failed: ${String(error)}` }],
        isError: true,
      };
    }
  },
};

const { session } = await createAgentSession({
  customTools: [lookupTicket],
});

toolNames requests tools and can enable tools that are disabled by default, but it is not an allowlist by itself. To restrict the session, set restrictToolNames: true. In a restricted session, a host tool is available only when all three are true:

const { session } = await createAgentSession({
  customTools: [lookupTicket],
  toolNames: ["lookup_ticket"],
  restrictToolNames: true,
  allowRestrictedCustomTools: true,
});

For reusable tools, commands, hooks, and UI integrations loaded from authored packages, use Extension authoring.

Control and clean up a sessionCopy Anchor Link

Calling prompt() while the session is already streaming requires streamingBehavior: "steer" or "followUp"; calling steer() or followUp() directly is clearer for most hosts.

Aside delivery (deliverAs: "aside") lands at the next safe step boundary without interrupting the current tool batch; the one exception is a running interruptible wait (or vibe_wait), which an aside ends so the message is not delayed behind it.

Handle failuresCopy Anchor Link

SDK or RPC?Copy Anchor Link

RPC starts with omp --mode rpc and exposes session events over stdio. Do not put an RPC subprocess behind the SDK merely to call the same process twice: choose the SDK for an in-process Bun host, or RPC for a real language/process boundary.

RelatedCopy Anchor Link

Source: omp.sh — MIT, Stencil Labs. Initially imported on 2026-10-03; updates via automatic sync.