Agent Runtime (Pi)
Relevant source files
The following files were used as context for generating this wiki page:
The Agent Runtime (Pi) is the execution environment and orchestration layer for intelligent agents within the Clawdbot ecosystem. It provides a structured framework for agents to interact with system tools, manage long-running background tasks, and execute complex workflows through a standardized interface. The runtime supports various models (e.g., Anthropic Claude, OpenAI GPT) and is specifically designed to handle interactive terminal applications via pseudo-terminal (PTY) allocation.
The runtime functions as an Intelligent Inversion of Control (IoC) container, where the session itself manages dependencies and agent wiring based on context and intent. It facilitates cross-session messaging, sub-agent spawning, and persistent state management, transforming general-purpose models into specialized agents equipped with procedural knowledge.
Sources: AGENTS.md:280-285, skills/coding-agent/SKILL.md:1-10, extensions/open-prose/skills/prose/help.md:38-45
System Architecture
The Agent Runtime (Pi) is built on a modular architecture that separates tool logic, system prompting, and execution management. It utilizes the @mariozechner/pi-agent-core and @mariozechner/pi-coding-agent libraries to provide a robust foundation for agent operations.
Core Components
| Component | Description |
|---|---|
| System Prompt Builder | Generates context-rich instructions for the LLM, including tool availability, workspace metadata, and user identity. |
| Tooling Layer | Provides a suite of functional tools for file I/O, shell execution, web searching, and session management. |
| Sandbox Environment | Executes agent commands within isolated Docker containers (when enabled) to ensure host security. |
| PTY Manager | Allocates pseudo-terminals for interactive CLI tools like Codex or Claude Code to prevent output breakage. |
Sources: src/agents/system-prompt.ts:130-160, skills/coding-agent/SKILL.md:12-20, package.json:165-170
Execution Flow
The runtime follows a specific sequence to initialize and execute an agent session. This process ensures that the agent is aware of its environment, limitations, and available resources before processing user requests.
System Prompting Logic
The buildAgentSystemPrompt function is the primary engine for configuring agent behavior. It supports three distinct modes: full (main agent), minimal (sub-agents), and none (basic identity).
Prompt Sections and Context
The prompt is dynamically constructed based on the current environment and configuration:
- Tooling: Lists available tools filtered by security policy. Core tools include
read,write,edit,exec, andprocess. - Workspace: Injects the current working directory and project-specific notes.
- Identity: Includes owner phone numbers for messaging surface recognition.
- Runtime Metadata: Appends a standardized "Runtime Line" containing
agent_id,host,os,node_version, andmodel. - Reasoning Format: Enforces
<think>...</think>tags for internal reasoning and<final>...</final>for user-visible replies.
Sources: src/agents/system-prompt.ts:13-110, src/agents/system-prompt.test.ts:10-40
The Runtime Line
Every Pi session includes a specific metadata string used for debugging and session tracking:
Runtime: agent=work | host=host | repo=/repo | os=macOS (arm64) | node=v20 | model=anthropic/claude | thinking=low
Sources: src/agents/system-prompt.ts:405-420, src/agents/system-prompt.test.ts:250-265
Tooling and Capabilities
The runtime exposes a broad set of tools that allow agents to manipulate their environment. These tools are case-sensitive and called via JSON-RPC or similar messaging protocols.
Essential Core Tools
exec: Runs shell commands. It supports apty: trueparameter, which is critical for interactive agents.process: Manages background execution sessions (list, poll, log, write, kill).sessions_spawn: Creates sub-agent sessions for parallel work or specialized tasks.message: Handles proactive sends and channel actions (polls, reactions) across Telegram, Signal, Discord, and Slack.gateway: Allows the agent to restart the daemon, apply configuration changes, or run self-updates.
Sources: src/agents/system-prompt.ts:145-175, skills/coding-agent/SKILL.md:22-35
Interactive Session Management
When running background agents, the runtime manages the interaction through a defined lifecycle:
Security and Sandboxing
The runtime implements security through optional Docker-based sandboxing and an "Elevated" access system.
- Sandboxing: When enabled, all file operations and
execcommands are confined to a container. Sub-agents inherit this sandboxed status. - Elevated Exec: Users can toggle execution levels:
off: Sandbox only.ask: Runs on host but requires explicit user approval.full: Auto-approves host execution (dangerous).
- Workspace Constraints: Agents are restricted to a defined
workspaceDirand are warned never to access sensitive directories like the core~/clawdbot/folder.
Sources: src/agents/system-prompt.ts:310-345, skills/coding-agent/SKILL.md:140-150
Implementation Details
The runtime is implemented in TypeScript (ESM) and relies on several key dependencies for its functionality.
Key Dependencies
@lydell/node-pty: Provides the pseudo-terminal support required for interactive CLIs.@mariozechner/pi-agent-core: Core agent logic and protocol handling.@agentclientprotocol/sdk: Implements the Agent Client Protocol for standardized communication.vitest: Used for comprehensive testing of system prompts and runtime logic.
Sources: package.json:165-185, CLAUDE.md:100-110
Runtime Configuration
The runtime state is persisted locally, typically in ~/.clawdbot/sessions/. The baseline requirement for execution is Node 22+.
Sources: CLAUDE.md:65-70, package.json:150-155
The Agent Runtime (Pi) serves as the critical bridge between abstract model reasoning and concrete system actions. By providing a structured, tool-rich environment with robust PTY and background process management, it enables Clawdbot to function as a sophisticated autonomous agent platform. Reaffirming the design, it ensures that even complex tasks like parallel PR reviews or multi-file coding projects can be orchestrated reliably within a secure, monitored environment.
Sources: AGENTS.md:280-285, skills/coding-agent/SKILL.md:155-170