Download the PHP package martin-ro/laravel-herdr without Composer

Laravel Herdr

A fluent, Laravel-style client for the Herdr terminal workspace socket API. It gives you an Eloquent-flavoured way to drive workspaces, tabs, panes, agents and worktrees, and to react to Herdr events — all from PHP.

Herdr's socket API is newline-delimited JSON over a local socket (a Unix domain socket on Linux/macOS, a named pipe on Windows). There is no network access and no authentication — your code talks to the Herdr instance running on the same machine. This package speaks that protocol for you.

Requirements

• PHP 8.2+
• Laravel 10, 11, 12 or 13
• A running Herdr instance on the same host

Installation

The service provider and Herdr facade are auto-discovered. To tweak defaults, publish the config:

Configuration

config/herdr.php (all values are env-driven):

Socket resolution order (mirrors Herdr's CLI): an explicit Herdr::session('name') → socket_path → session → the default ~/.config/herdr/herdr.sock.

Usage

Everything hangs off the Herdr facade (or the herdr() helper, or type-hinting MartinRo\Herdr\HerdrManager).

Workspaces, tabs, panes

Objects returned from reads are live — they carry a connection, so you can act on them directly:

Driving a pane

Agents

Agents are addressed by a target: their unique live name, or the id of the pane hosting them. The agent field is the kind, e.g. "claude".

Declarative agent views filter and sort the sidebar's agent list:

Report agent state for a pane you control (e.g. from a custom CI runner):

Worktrees

Notifications & window title

Events

Herdr pushes events over the socket after you subscribe. Because reading events blocks, run an event loop on its own connection — typically an artisan command or queue worker, not a web request.

Subscription types use dotted names (pane.created). The pushed envelopes use underscore names and nest the payload under data, with full info objects embedded where applicable; $event->name(), $event->data() and $event->pane() unwrap this for you. Data-bearing subscriptions require scope fields: pane.agent_status_changed and pane.scroll_changed require pane_id; pane.output_matched requires pane_id, source and a match.

Block until a single event arrives (server-side, on a one-shot request). As of Herdr 0.7.5 the server only supports pane agent-status matches here:

Or client-side over a subscription stream:

Session snapshot & layouts

Plugins & integrations

Multiple sessions

Escape hatch

Every documented method is reachable, but for anything not yet wrapped (or new Herdr methods) call the raw API directly:

Returned Data/Result objects are permissive: typed accessors exist for the documented fields, and every field is reachable via ->field, ['field'], ->get('dot.path'), or ->toArray() — so undocumented or newly-added fields are never lost.

Error handling

find() helpers swallow not-found errors (Herdr namespaces them per resource, e.g. pane_not_found, workspace_not_found) and return null:

Testing

Fake the transport with Herdr::fake() — no socket required. Stub responses by method name and assert what was sent, just like Http::fake().

Drive the event stream in tests by queuing events:

Run the package's own suite:

Architecture

• One request per connection. Herdr serves a single response per socket and then closes it, so each call opens a fresh connection. Subscriptions are the exception: the socket stays open and the server pushes events down it. The Herdr manager is a safe long-lived singleton — it opens connections on demand, so you never hold a dead socket.
• Framing is exact: one JSON object per line, terminated by \n; the reader buffers partial reads and splits multiple messages that arrive in one chunk.
• Correlation: each request gets a unique id; responses are matched by it, and any unsolicited event lines (which carry no id) are parked for the event stream.
• Data objects wrap raw attributes permissively, so the package keeps working even where Herdr's response fields are undocumented or evolve.

Field names and the connection model in this package were verified against a live Herdr 0.7.5 server (socket protocol 17).

License

MIT.