Agent SDK

The Agent SDK runs the Nib agent from your own code. You send a prompt and get a stream of typed messages back. Tools you define, hooks and permission decisions run in your process; the agent itself runs in the Nib daemon, so every SDK session is an ordinary Nib session that you can open in the desktop app or resume with nib --resume.

The API is small: query() with options, a typed message stream, and your own tools, hooks and permission callbacks.

A first queryCopy Anchor Link

import { query } from "@nibapp/agent-sdk";

for await (const message of query({ prompt: "Find and fix the flaky test" })) {
  if (message.type === "result") console.log(message.result, message.total_cost_usd);
}

query() streams these messages:

While a query runs, you can call interrupt(), setModel(), setPermissionMode() and rewindFiles() on it. Pass an async iterable of messages as the prompt to stream follow-ups.

For a back-and-forth conversation, use NibSDKClient: connect(), query(), receiveResponse(), interrupt() and disconnect(). In TypeScript it supports await using.

Approving tool calls from codeCopy Anchor Link

canUseTool decides any tool call that isn't already allowed by the permission mode or allowedTools. It also answers the agent's multiple-choice questions.

const run = query({
  prompt: "Run the test suite and fix the first failure",
  options: {
    allowedTools: ["Read", "Grep", "Glob", "Bash(bun test:*)"],
    canUseTool: async (toolName, input, { title }) =>
      (await confirm(`Allow ${title ?? toolName}?`))
        ? { behavior: "allow" }
        : { behavior: "deny", message: "The user declined" },
  },
});

canUseTool is one input to Nib's permission engine, not a way around it. Deny rules and protected paths still apply, and the sandbox still contains shell commands.

Your own toolsCopy Anchor Link

Define tools in your process and hand them to the agent as an in-process MCP server. The agent sees them as mcp__<server>__<tool>.

import { z } from "zod";
import { createSdkMcpServer, query, tool } from "@nibapp/agent-sdk";

const tracker = createSdkMcpServer({
  name: "tracker",
  tools: [
    tool("get_ticket", "Look up a ticket by key", { key: z.string() }, async ({ key }) => ({
      content: [{ type: "text", text: await lookUp(key) }],
    })),
  ],
});

for await (const message of query({
  prompt: "Fix TICKET-1",
  options: { mcpServers: { tracker }, allowedTools: ["mcp__tracker__get_ticket"] },
})) {
  if (message.type === "result") console.log(message.result);
}

HooksCopy Anchor Link

hooks takes callbacks for the same events as hooks in settings (PreToolUse, PostToolUse, Stop and so on), with the same input and output JSON. In Python, register them with HookMatcher(matcher="Bash", hooks=[...]).

OptionsCopy Anchor Link

Option names are camelCase in TypeScript and snake_case in Python (allowed_tools, permission_mode, max_budget_usd…).

A program enters bypassPermissions only on its own word: it starts the query in that mode, and only such a query can switch to it later with setPermissionMode(). A person's acceptance of bypass in the terminal UI, -p or an editor doesn't open it, because an SDK program is code that someone else may have written, so it opts in in its own source.

How it worksCopy Anchor Link

query() starts nib -p --input-format stream-json --output-format stream-json and talks to it over standard input and output. Your in-process tools and hooks are served to the agent by the CLI on a loopback endpoint with a random port and token, and each call is forwarded to your process. Both SDKs speak the same protocol.

Behavior to knowCopy Anchor Link

• The default system prompt is Nib's complete agent prompt, not a minimal one.
• rewindFiles(userMessageId) rewinds the conversation as well as the files. The id comes from the result's user_message_id.

NextCopy Anchor Link

• Permissions: modes and rule syntax.
• Budgets and receipts: what a run costs.