Skip to content

Local Unix socket client

Control Herdr from Python.

A small, typed client for inspecting workspaces, driving panes and listening to events without adding runtime dependencies.

Get started Explore the API

python -m pip install herdr-client
Python 3.13+ Sync + Async 0 runtime deps
herdr-client / quickstart
$ python demo.py
connecting to ~/.config/herdr/herdr.sock
connected protocol=22

workspace main
pane build / ready
output tests passed

Built for local automation

Small surface. Useful everywhere.

  • One API, two styles

    Use blocking methods in scripts or native asyncio methods in services. Names, parameters and return types stay aligned.

    Choose a client

  • Typed, not restrictive

    Results are ordinary dictionaries with schema-derived TypedDict models, so callers keep familiar indexing and iteration.

    Explore the types

  • Local by default

    Connect through an explicit socket, an environment variable or a named Herdr session with predictable resolution rules.

    Configure the socket

Start in seconds

Pick your style.

Both clients expose the same operations. Choose a tab and keep that choice across the rest of the documentation.

from herdr_client import HerdrClient

client = HerdrClient()
print(client.ping())
print(client.workspace_list())

import asyncio

from herdr_client import AsyncHerdrClient


async def main() -> None:
    client = AsyncHerdrClient()
    print(await client.ping())
    print(await client.workspace_list())


asyncio.run(main())

Keep going

Find the right starting point.