Architecture
PP Agent is an Electron app plus a headless Node daemon. The split keeps a slow tool from freezing the window and lets the agent outlive it.
Processes
Section titled “Processes”| Component | Role |
|---|---|
| Renderer | The React interface: chat, settings, side panel, approvals |
| Main process | Windows, dialogs, the preload bridge, and desktop integration |
| Daemon | pp-agentd: Pi SDK sessions, the key vault, tools, MCP connections, and chat channels |
| Preload bridge | A narrow, validated contract between the renderer and main |
| Mobile/web app | The same web app in a Capacitor shell, or served on the local network by the daemon |
The renderer talks to main through the preload bridge. Main talks to the daemon over a local socket with NDJSON frames. The daemon also handles the Telegram and Zalo chat channels.
Request flow
Section titled “Request flow”- You send a prompt with optional attachments.
- The daemon builds the conversation context for the selected model.
- The model returns text or a tool call.
- A tool call passes the approval gate: read-only tools run, consequential tools ask according to their policy.
- Tool results return to the model.
- The reply streams to the renderer, and the conversation is saved.
Where features live
Section titled “Where features live”| Area | Component |
|---|---|
| Chat and approvals | Daemon (session and tool gate), renderer (UI) |
| Settings and agents | Shared contract, main process, daemon apply |
| MCP servers | Daemon, registered per agent |
| Side panel | Main process (terminal, browser), renderer (files and tabs) |
| Scheduled tasks | Daemon |
| Remote access | Daemon HTTP server plus the web app in a mobile layout |
| Channels | Daemon (Telegram, Zalo polling and pairing) |
| Vault | Daemon, backed by the OS keychain or PP_AGENT_MASTER_KEY |
Security boundaries
Section titled “Security boundaries”- The renderer has no Node.js access; every privileged operation goes through the preload bridge.
- IPC input and file paths are validated in the main process.
- Keys are decrypted in the daemon, not in the renderer.
- Every tool call passes the approval gate, including calls from scheduled and channel runs.
Going deeper
Section titled “Going deeper”The repository’s developer documentation covers the process model, IPC frames, storage, conversation flows, providers and MCP, the side panel, remote access, and the mobile app:
Related: Security and privacy, Data storage.