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
cwd
string
default:"process.cwd()"
Working directory for project-local discovery
agentDir
string
default:"~/.pi/agent"
Global config directory
Auth storage for credentials. Default: AuthStorage.create(agentDir/auth.json)
Model registry. Default: new ModelRegistry(authStorage, agentDir/models.json)
Model to use. Default: from settings, else first available
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]
Custom tools to register in addition to built-in tools
Resource loader. When omitted, DefaultResourceLoader is used
Session manager. Default: SessionManager.create(cwd)
Settings manager. Default: SettingsManager.create(cwd, agentDir)
Returns
The created agent session
Extensions result for UI context setup in interactive mode
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(),
});
cwd, you must use tool factory functions to ensure tools resolve paths relative to your cwd, not process.cwd().
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';
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),
],
});
Full access mode: [read, bash, edit, write]
Read-only exploration: [read, grep, find, ls]
All available built-in tools as a keyed object
Type Exports
export type {
ExtensionAPI,
ExtensionCommandContext,
ExtensionContext,
ExtensionFactory,
SlashCommandInfo,
SlashCommandLocation,
SlashCommandSource,
ToolDefinition,
PromptTemplate,
Skill,
Tool,
};