Plugins¶
Pynchy is a personal AI assistant that routes messages from channels (WhatsApp, Slack, etc.) to LLM agents running in isolated containers. For an overview, see the architecture.
Pynchy stays minimal by design. New capabilities — channels, tools, skills, agent cores — are added as plugins, not features in the base codebase.
Plugins come as regular Python packages, discovered automatically at startup. Install a plugin, restart Pynchy, done.
Plugin Categories¶
| Category | Hook | What it provides | Runs where |
|---|---|---|---|
| Agent Core | pynchy_agent_core_info() | LLM framework (Claude SDK, OpenAI, Ollama) | Container |
| Service Handler | pynchy_service_handler() | Typed host-action descriptors and handlers dispatched via IPC | Host |
| Semantic Actions | pynchy_action_specs() | Plugin-owned action IDs, surfaces, and evidence requirements | Host |
| Skill | pynchy_skill_paths() | Agent instructions and capabilities (markdown) | Container |
| Channel | pynchy_create_channel() | Communication platform (Telegram, Slack, Discord) | Host |
| Connection Runtime | pynchy_connection_runtime() | Authenticated provider polling or subscription lifecycle | Host |
| Speech Synthesis | pynchy_speech_synthesizer() | Final spoken replies for channels | Host |
| Container Runtime | pynchy_container_runtime() | Container runtime implementation (Docker, Apple Container) | Host |
| Tunnel | pynchy_tunnel() | Remote connectivity detection (Tailscale, Cloudflare, etc.) | Host |
| Observer | pynchy_observer() | Event persistence and processing (SQLite, OpenTelemetry) | Host |
| MCP Server | pynchy_mcp_server_spec() | On-demand tool servers (Docker or script) | Host + Container |
| Workspace | pynchy_workspace_spec() | Managed workspace/task definitions (e.g. periodic agents) | Host |
A single plugin can implement multiple hooks. A "voice" plugin might provide both an MCP server (transcription tools) and a skill (voice interaction patterns).
LLM Gateway: Regardless of which Agent Core plugin is active, all LLM API calls route through a host-side LiteLLM gateway. This provides automatic load balancing across APIs, access to 100+ LLM providers, and credential isolation — containers never see real API keys. Configure it via
data/personalization/litellm.yaml(see Container Isolation — Environment Variable Isolation).
How Discovery Works¶
App starts
→ get_plugin_manager() creates a pluggy PluginManager
→ Registers built-in plugins from static registry
→ Discovers third-party plugins via Python entry points
→ Ready: pm.hook.pynchy_agent_core_info(), etc.
Built-in plugins live in the monorepo and load from the static registry in src/pynchy/plugins/registry.py. Plugins with optional dependencies (WhatsApp, Slack, Discord, CalDAV, and notebook support) are gracefully skipped if their packages are not installed.
Third-party plugins register via pyproject.toml entry points in the "pynchy" group. Installing makes them discoverable and uninstalling removes them; the plugin's own documentation determines whether credentials or configuration are also required.
Security Model¶
All plugin Python code runs on the host during discovery. See Security Model for the full trust model.
| Category | Sandbox Level | Risk |
|---|---|---|
| Channel | None — runs persistently in host process | Highest |
| Connection Runtime | None — owns provider credentials and runs persistently | Highest |
| Speech Synthesis | None — host-side model/service client | High |
| Container Runtime | None — host-side process management | Highest |
| Tunnel | None — host-side network detection | High |
| Service Handler | None — host-side handlers with policy enforcement | High |
| Observer | Host-side event subscriber, writes to DB or external services | High |
| MCP Server | Docker-isolated or host-side script; LiteLLM proxied | Medium |
| Workspace | Host-side config only — agent runs in container | Medium |
| Skill | Partial — skill_paths() on host, content in container | Medium |
Next Steps¶
- Available Plugins — Browse built-in plugins and community listings
- Quickstart — Build your first plugin in 5 minutes
- Hook Reference — All plugin hooks and return value schemas
- Packaging — Entry points, distribution, installation