BranchKit Plugin SDK (Python)

The Python SDK for building BranchKit plugins — processes (run under BranchKit's managed CPython) that add voice commands, window management, browser integration, or anything else to the BranchKit platform. MIT licensed. Feature-parity with the Go and TypeScript SDKs, verified by a shared conformance harness. Stdlib-only: importing the SDK forces no third-party dependency on any plugin.

Start here

• Your First Plugin — working plugin in ~10 minutes
• Plugin Anatomy — manifest, lifecycle, methods
• Plugin API Reference — every wire method, generated from the OpenRPC spec

Minimal plugin

import asyncio
import branchkit

plugin = branchkit.Plugin()

@plugin.handle_action("myplugin.greet")
async def greet(req):
    await plugin.input_type_text("Hello!")
    return {"status": "ok"}

asyncio.run(plugin.run())

Pair with a plugin.json manifest declaring the action and "runtimes": ["python"] (run: "python3 main.py") — see the tutorial. branchkit-gen generates typed params (TypedDict) and registrars from your manifest's action_types.

Handlers may be async def (run on the asyncio loop) or plain def (auto-offloaded to a worker thread, so a blocking body cannot freeze the plugin — use plugin.call_sync(...) there instead of await).

Key surfaces

Development

python3 -m unittest discover -s tests     # the SDK's own suite

The cross-language conformance suite lives in the app workspace (branchkit-sdk-test against sdk-test/testplugin-py). Generated files (*_gen.py) are emitted by emit-sdk — edit the inventory, not the files.