SDK API

Core SDK functions for creating agent sessions and managing tools

createAgentSession()

Create an agent session with automatic discovery of extensions, skills, and tools.

import { createAgentSession } from '@mariozechner/pi-coding-agent';

const { session, extensionsResult } = await createAgentSession({
  cwd: process.cwd(),
  model: myModel,
  tools: codingTools,
});

Parameters

options · CreateAgentSessionOptions

Configuration for the agent session

Show properties

cwd · string · default: "process.cwd()"

Working directory for project-local discovery

agentDir · string · default: "~/.pi/agent"

Global config directory

authStorage · AuthStorage

Auth storage for credentials. Default: AuthStorage.create(agentDir/auth.json)

modelRegistry · ModelRegistry

Model registry. Default: new ModelRegistry(authStorage, agentDir/models.json)

model · Model<any>

Model to use. Default: from settings, else first available

thinkingLevel · ThinkingLevel

Thinking level. Default: from settings, else ‘medium’ (clamped to model capabilities)

scopedModels · Array<{ model: Model<any>; thinkingLevel: ThinkingLevel }>

Models available for cycling (Ctrl+P in interactive mode)

tools · Tool[] · default: "codingTools"

Built-in tools to use. Default: [read, bash, edit, write]

customTools · ToolDefinition[]

Custom tools to register in addition to built-in tools

resourceLoader · ResourceLoader

Resource loader. When omitted, DefaultResourceLoader is used

sessionManager · SessionManager

Session manager. Default: SessionManager.create(cwd)

settingsManager · SettingsManager

Settings manager. Default: SettingsManager.create(cwd, agentDir)

Returns

CreateAgentSessionResult · object

Show properties

session · AgentSession

The created agent session

extensionsResult · LoadExtensionsResult

Extensions result for UI context setup in interactive mode

modelFallbackMessage · string | undefined

Warning if session was restored with a different model than saved

Examples

Minimal Usage

Uses all defaults: discovers skills, extensions, tools, and context files from cwd and ~/.pi/agent.

import { createAgentSession } from '@mariozechner/pi-coding-agent';

const { session } = await createAgentSession();

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

await session.prompt('What files are in the current directory?');

With Explicit Model

import { getModel } from '@mariozechner/pi-ai';
import { createAgentSession } from '@mariozechner/pi-coding-agent';

const { session } = await createAgentSession({
  model: getModel('anthropic', 'claude-opus-4-5'),
  thinkingLevel: 'high',
});

Full Control

import { createAgentSession, DefaultResourceLoader, SessionManager } from '@mariozechner/pi-coding-agent';
import { getAgentDir } from '@mariozechner/pi-coding-agent';

const loader = new DefaultResourceLoader({
  cwd: process.cwd(),
  agentDir: getAgentDir(),
  settingsManager: SettingsManager.create(),
});
await loader.reload();

const { session } = await createAgentSession({
  model: myModel,
  tools: [readTool, bashTool],
  resourceLoader: loader,
  sessionManager: SessionManager.inMemory(),
});

Tool Factories

When using a custom cwd, you must use tool factory functions to ensure tools resolve paths relative to your cwd, not process.cwd().

Pre-built Tools

These use process.cwd() as the working directory:

import {
  readTool,
  bashTool,
  editTool,
  writeTool,
  grepTool,
  findTool,
  lsTool,
  codingTools,      // [read, bash, edit, write]
  readOnlyTools,    // [read, grep, find, ls]
  allBuiltInTools,  // All built-in tools
} from '@mariozechner/pi-coding-agent';

Tool Factories (for custom cwd)

import {
  createCodingTools,
  createReadOnlyTools,
  createReadTool,
  createBashTool,
  createEditTool,
  createWriteTool,
  createGrepTool,
  createFindTool,
  createLsTool,
} from '@mariozechner/pi-coding-agent';

const customCwd = '/path/to/project';

// Full coding toolset for custom directory
await createAgentSession({
  cwd: customCwd,
  tools: createCodingTools(customCwd),
});

// Individual tools for custom directory
await createAgentSession({
  cwd: customCwd,
  tools: [
    createReadTool(customCwd),
    createBashTool(customCwd),
    createGrepTool(customCwd),
  ],
});

Tool Sets

codingTools · Tool[]

Full access mode: [read, bash, edit, write]

readOnlyTools · Tool[]

Read-only exploration: [read, grep, find, ls]

allBuiltInTools · Record<ToolName, Tool>

All available built-in tools as a keyed object

Type Exports

export type {
  ExtensionAPI,
  ExtensionCommandContext,
  ExtensionContext,
  ExtensionFactory,
  SlashCommandInfo,
  SlashCommandLocation,
  SlashCommandSource,
  ToolDefinition,
  PromptTemplate,
  Skill,
  Tool,
};