Skip to content

Plugin hook reference

Pynchy plugins implement hooks defined in src/pynchy/plugins/hookspecs.py. Each hook represents one capability; a plugin can implement several.

All hooks use Pluggy's decorator:

import pluggy

hookimpl = pluggy.HookimplMarker("pynchy")

Choose a hook category

Category Hooks
Agent cores and lifecycle hooks pynchy_agent_core_info, pynchy_agent_hook_specs, pynchy_before_context_reset
Host services pynchy_service_handler, pynchy_computer_use_backend, pynchy_action_specs
Skills pynchy_skill_paths
Channels and speech pynchy_create_channel, pynchy_speech_synthesizer
Connection runtimes pynchy_connection_runtime
Runtime and tunnels pynchy_container_runtime, pynchy_tunnel
Observers pynchy_observer
Webhooks pynchy_webhook_routes
MCP servers, workspaces, and jobs pynchy_mcp_server_spec, pynchy_workspace_spec, pynchy_job_specs

Multi-category plugins

One plugin can implement several hooks:

class CalendarPlugin:
    @hookimpl
    def pynchy_service_handler(self) -> HostActionRegistration:
        return CALENDAR_HOST_ACTIONS

    @hookimpl
    def pynchy_action_specs(self) -> tuple[ActionSpec, ...]:
        return CALENDAR_ACTION_SPECS

    @hookimpl
    def pynchy_skill_paths(self) -> list[str]:
        return [str(Path(__file__).parent / "skills" / "calendar")]

No categories attribute is needed. Pluggy discovers capabilities from the hooks the class implements.

Hook execution order

Most plugins do not need ordering. Use a Pluggy ordering hint only when one plugin must see or modify another plugin's result:

@hookimpl(trylast=True)
@hookimpl(tryfirst=True)