Socket API

The flockr server listens on a local socket. The flockr CLI, agent integration hooks, and plugins all control flockr through it. Your own scripts can use it too.

The socket

Inside a flockr pane, FLOCKR_SOCKET_PATH holds the session's socket path. flockr status and flockr session list also print it.

Use the CLI first

Most methods have a CLI command that sends the request and prints the JSON response. In a script this is usually the simplest route:

pane=$(flockr pane split --current --direction right --no-focus | jq -r '.result.pane.pane_id')
flockr pane run "$pane" "just test"
flockr pane wait-output "$pane" --match "test result" --timeout 120000

Read IDs from the JSON responses instead of guessing them. See the CLI reference.

Wire format

Requests and responses are JSON, one object per line. A request has an id, a method, and params:

{"id":"1","method":"ping","params":{}}

A success response echoes the id and carries a result:

{"id":"1","result":{"type":"pong","version":"1.1.0","protocol":22,"capabilities":{...}}}

An error response carries an error with a code and a message.

A minimal client in Python:

import json, os, socket

s = socket.socket(socket.AF_UNIX)
s.connect(os.environ["FLOCKR_SOCKET_PATH"])
s.sendall(json.dumps({"id": "1", "method": "agent.list", "params": {}}).encode() + b"\n")
print(s.makefile().readline())

The schema

Every request, response, and event is described by a JSON Schema (draft 2020-12). It ships inside the binary:

flockr api schema                          # summary: protocol, schema version, sections
flockr api schema --json                   # the full schema
flockr api schema --output flockr-api.schema.json

The repository also has it at docs/next/api/flockr-api.schema.json. It has five sections: request, success_response, error_response, event, and subscription_event. The schema carries the protocol number (22 at the time of writing); flockr status shows the client's and server's protocol.

Methods

Methods are grouped by prefix. The schema lists every method and its params.

Events

events.subscribe takes a list of subscriptions and streams events on the same connection. events.wait waits for one matching event, with an optional timeout_ms.

Event kinds include workspace_created, workspace_closed, workspace_focused, worktree_created, tab_created, tab_focused, pane_created, pane_closed, pane_focused, pane_exited, pane_agent_detected, pane_agent_status_changed, and layout_updated. Subscription events add pane.output_matched, pane.agent_status_changed, and pane.scroll_changed. The schema has the full list.

Live snapshot

flockr api snapshot

Prints the whole session as JSON: spaces, tabs, panes, and agents with their state, working directory, and branch. It is the same data as the session.snapshot method.

How hooks and plugins use it

• Integration hooks read FLOCKR_PANE_ID and FLOCKR_SOCKET_PATH from the pane's environment and send pane.report_agent_session (and for some agents pane.report_agent) over the socket. You can do the same from a wrapper script with flockr pane report-agent.
• Plugins run with FLOCKR_SOCKET_PATH and other FLOCKR_* variables set, and call the CLI or the socket. Plugins written for herdr also get the HERDR_* names; see flockr and herdr.
• Display metadata: pane.report_metadata and workspace.report_metadata set titles, labels, and $name tokens for the sidebar.

Versions

After an update, the client and a running server can be different versions. Check flockr status before relying on a new method. A missing method means the server is older; it is not a reason to stop the server.