872b0adb48
Split flat docs/ into user-docs/ (guides, config, troubleshooting) and dev/ (ADRs, architecture, extension guides, proposals). Updated docs/README.md index to reflect new paths.
2.5 KiB
2.5 KiB
Architecture & Mental Model
┌─────────────────────────────────────────────────────┐
│ Pi Runtime │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Session │ │ Agent │ │ Tool Executor │ │
│ │ Manager │ │ Loop │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
│ │ │ │ │
│ └──────────────┼─────────────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ Event System │ ◄── All events flow │
│ └───────┬────────┘ through here │
│ │ │
│ ┌────────────┼────────────┐ │
│ ▼ ▼ ▼ │
│ Extension A Extension B Extension C │
│ │
└─────────────────────────────────────────────────────┘
Key concepts:
- Extensions are loaded once when pi starts (or on
/reload). Your default export function runs, and you subscribe to events and register tools/commands during that function call. - Events are the communication mechanism. Pi emits events at every stage of its lifecycle. Your extension listens and reacts.
- Tools are the LLM's interface to your extension. The LLM sees tool descriptions in its system prompt and calls them when appropriate.
- Commands are the user's interface. Users type
/mycommandto invoke your extension directly. - State lives in tool result
detailsfor proper branching/forking support, or inpi.appendEntry()for extension-private state.