Documentation Index Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt
Use this file to discover all available pages before exploring further.
The AgentSession class is the central abstraction for agent lifecycle and session management. It provides access to agent state, event subscription with automatic persistence, model management, compaction, and session operations.
Import import { AgentSession } from "@mariozechner/pi-coding-agent" ;
Constructor new AgentSession ( config : AgentSessionConfig )
config
AgentSessionConfig
required
Configuration object for the agent session The underlying agent instance from @mariozechner/pi-agent-core
Manager for session persistence and history
Manager for user settings (compaction, images, etc.)
Current working directory for tool operations
scopedModels
Array<{ model: Model; thinkingLevel: ThinkingLevel }>
Models to cycle through with keyboard shortcuts
Loader for skills, prompts, themes, and context files
Custom tools registered outside extensions
Registry for API key resolution and model discovery
Initial active tool names. Default: ["read", "bash", "edit", "write"]
Properties Access to the underlying agent instance
Access to the session manager
Current working directory
Methods addEventListener Subscribe to agent session events.
addEventListener ( listener : AgentSessionEventListener ): void
listener
(event: AgentSessionEvent) => void
required
Callback function that receives session events
Events:
agent_start - Agent turn beginsagent_end - Agent turn completestool_execution_start - Tool execution beginstool_execution_end - Tool execution completesauto_compaction_start - Automatic compaction triggeredauto_compaction_end - Automatic compaction finishedAnd more (see AgentSessionEvent type)
prompt Send a user message to the agent.
prompt ( text : string , options ?: PromptOptions ): Promise < ModelCycleResult >
File attachments to include with the message
Whether to auto-compact context if needed. Default: true
executeBash Execute a bash command.
executeBash ( command : string , description ?: string ): Promise < BashResult >
The bash command to execute
Optional description of the command
compact Manually trigger context compaction.
compact ( options ?: CompactOptions ): Promise < CompactionResult >
Target token count after compaction
switchSession Switch to a different session.
switchSession ( sessionId : string ): Promise < void >
The ID of the session to switch to
getState Get current agent state.
Returns the current agent state including messages, model, thinking level, and streaming status.
Example import { createAgentSession } from "@mariozechner/pi-coding-agent" ; const { session , extensionRunner } = await createAgentSession ({ cwd: process . cwd (), model: getModel ( "anthropic" , "claude-4.5-sonnet-20250514" ), thinkingLevel: "medium" , }); // Subscribe to events session . addEventListener (( event ) => { if ( event . type === "tool_execution_start" ) { console . log ( `Tool: ${ event . toolName } ` ); } }); // Send a message const result = await session . prompt ( "List files in the current directory" ); console . log ( result . messages );
Type Definitions SessionStats Statistics about the current session.
interface SessionStats { messageCount : number ; tokenCount : number ; compactionCount : number ; }
ModelCycleResult Result from a prompt operation.
interface ModelCycleResult { messages : AgentMessage []; aborted : boolean ; error ?: string ; }