Architecture¶

How Pynchy works under the hood. Read this to troubleshoot issues, reason about security boundaries, and extend the system through plugins.

System Overview¶

graph TB
    subgraph plugins ["Plugins"]
        CH["Channels"] ~~~ AC["Agent Cores"] ~~~ INT["Integrations"] ~~~ OBS["Observers"]
        TUN["Tunnels"] ~~~ RT["Runtimes"]
    end

    subgraph host ["Host"]
        Registry["Plugin Registry"] ~~~ Messaging
        Orchestrator ~~~ ContainerMgr["Container Manager"]
        MCP["MCP Manager"] ~~~ Security["Security Gate + Cop"]
        Gateway["LLM Gateway"]
    end

    Agent["Agent Containers"]
    MCPCont["MCP Containers"]

    plugins -. "hooks" .-> Registry
    Registry --> Orchestrator
    Registry --> MCP
    Messaging <--> Orchestrator
    Orchestrator <--> ContainerMgr
    ContainerMgr <--> Security
    MCP --> MCPCont
    Security <--> Agent
    Security <--> MCPCont
    Gateway <--> Agent

Core Systems¶

Topic	What it covers
Container isolation	Mounts, runtime plugins, environment variables
Configuration layers	Public defaults, private personalization, secrets, validation, and runtime state
IPC	File-based communication between containers and host
Message routing	Routing behavior, transparent token stream
Routed conversations	Stable external subjects, FIFO delivery claims, and replaceable Discord controls
Message types	Type system, storage, SDK integration
Service boundaries	Package roles, public surfaces, contracts, and baseline burn-down
Git sync	Coordinated worktree sync, host-mediated merges
Security	Trust model, security boundaries, credential handling
MCP management	McpManager internals, instance deduplication, LiteLLM integration
Action coverage	Semantic action catalog, hermetic test gate, and real-service canary contract
Memory and sessions	Obsidian memory, automatic learning, automation memory, and session management

Pluggable Subsystems¶

Each subsystem below is backed by a pluggy hook and can be extended or replaced via plugins.

Topic	Hook	What it covers
Observers	`pynchy_observer`	Event bus, event types, persistence
Tunnels	`pynchy_tunnel`	Connectivity detection, startup checks
Workspaces	`pynchy_workspace_spec`	Managed workspace definitions, config merging
MCP service tools	`pynchy_service_handler`	Host-side tool handlers, security policy

For user-facing documentation on pluggable subsystems (channels, agent cores, and host services), see Usage. For the full list of plugin hooks, see Hook Reference.