From bb7b1c00fe6babfc0701480436bdbb4c2443ef2e Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Sat, 23 May 2026 18:01:21 +0300 Subject: docs: finalize next release docs --- website/src/content/docs/socket-api.mdx | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'website/src/content/docs/socket-api.mdx') diff --git a/website/src/content/docs/socket-api.mdx b/website/src/content/docs/socket-api.mdx index c4de1b3d..4d32817e 100644 --- a/website/src/content/docs/socket-api.mdx +++ b/website/src/content/docs/socket-api.mdx @@ -71,6 +71,7 @@ Raw socket method names use dot notation: | --- | --- | | Server | `ping`, `server.stop`, `server.reload_config` | | Workspace | `workspace.create`, `workspace.list`, `workspace.get`, `workspace.focus`, `workspace.rename`, `workspace.close` | +| Worktree | `worktree.list`, `worktree.create`, `worktree.open`, `worktree.remove` | | Tab | `tab.create`, `tab.list`, `tab.get`, `tab.focus`, `tab.rename`, `tab.close` | | Pane | `pane.split`, `pane.list`, `pane.get`, `pane.rename`, `pane.send_text`, `pane.send_keys`, `pane.send_input`, `pane.read`, `pane.report_agent`, `pane.clear_agent_authority`, `pane.release_agent`, `pane.close`, `pane.wait_for_output` | | Agent | `agent.list`, `agent.get`, `agent.read`, `agent.send`, `agent.rename`, `agent.focus`, `agent.start` | @@ -79,6 +80,28 @@ Raw socket method names use dot notation: Some CLI commands are conveniences around these methods. For example, `herdr agent wait` resolves an agent target and then subscribes to pane agent state events. +Worktree methods manage Git checkouts as Herdr workspaces. `worktree.create` creates a checkout and returns the new `workspace`, `tab`, `root_pane`, and `worktree` records. `worktree.open` opens an existing checkout or returns the already-open workspace. `worktree.remove` runs `git worktree remove` against a linked child workspace and never deletes the branch. + +Create a worktree from a source workspace: + +```json +{"id":"req_1","method":"worktree.create","params":{"workspace_id":"1","branch":"worktree/api","focus":false}} +``` + +Open an existing checkout: + +```json +{"id":"req_2","method":"worktree.open","params":{"workspace_id":"1","branch":"worktree/api","focus":true}} +``` + +Remove a linked checkout: + +```json +{"id":"req_3","method":"worktree.remove","params":{"workspace_id":"2","force":false}} +``` + +Use at most one of `workspace_id` or `cwd` for `worktree.list`, `worktree.create`, and `worktree.open`; omit both to use the active workspace. Use exactly one of `path` or `branch` for `worktree.open`. Raw socket `cwd` and `path` values must be absolute; the CLI expands relative `--cwd` and `--path` values before sending requests. Workspace responses include optional `worktree` provenance when a workspace belongs to a Herdr worktree group. Worktree commands can emit `workspace.updated` when an existing workspace gains or changes worktree provenance. + ## Socket transport Herdr uses newline-delimited JSON over a Unix domain socket. @@ -158,6 +181,8 @@ Subscribe to events when you need a long-lived stream: The first response acknowledges the subscription. Later lines are pushed events. +Workspace event subscriptions include `workspace.created`, `workspace.updated`, `workspace.renamed`, `workspace.closed`, and `workspace.focused`. + Use `events.wait` when you want one matching event and then a response. ## Reading panes -- cgit v1.2.3