API reference
API level 9. Clients speak newline-delimited JSON over the daemon’s unix
socket (hive api schema prints this as JSON Schema; pkg/hiveapi is the Go SDK;
the README’s “Wire protocol” section has the framing). A protocol-2 client
opens with {"type":"hello","version":"2","params":{"client":"my-tool"}}, then
sends requests such as
{"version":"2","type":"request","id":"1","method":"agent.list","params":{"all":true}},
each answered by a response with the same id and a result or an error
(code, message). Pipe methods answer, then carry a byte stream on the
connection. Every name below is stable within 1.x (the compatibility policy).
agent
agent.explain
Result: agent.Explanation
agent.focus
Result: agent.Agent
agent.get
Result: agent.Agent
agent.list
Result: agent.ListResult
agent.manifests
No params.
Result: []agent.Manifest
agent.prompt
| Param |
Type |
|
id |
string |
|
read |
integer |
|
stall_timeout_ms |
integer |
|
start_timeout_ms |
integer |
|
text |
string |
|
timeout_ms |
integer |
|
until |
string |
|
wait |
boolean |
|
Result: agent.PromptResult
agent.read
| Param |
Type |
|
ansi |
boolean |
|
id |
string |
|
lines |
integer |
|
source |
string |
|
Result: []string
agent.reload
No params.
Result: agent.ReloadResult
agent.rename
| Param |
Type |
|
id |
string |
|
name |
string |
|
Result: agent.Agent
agent.report
| Param |
Type |
|
id |
string |
|
message |
string |
|
session_id |
string |
|
state |
string |
|
ttl_ms |
integer |
|
Result: agent.Agent
agent.seen
Result: map[string]boolean
agent.send_keys
| Param |
Type |
|
id |
string |
|
keys |
[]string |
|
Result: map[string]boolean
agent.start
| Param |
Type |
|
args |
[]string |
|
base |
string |
|
env |
map[string]string |
|
environment_id |
string |
|
kind |
string |
|
name |
string |
|
worktree |
string |
|
Result: runtime.AgentStarted
agent.stop
Result: agent.Agent
agent.wait
| Param |
Type |
|
after |
integer |
|
id |
string |
|
stall_ms |
integer |
|
timeout_ms |
integer |
|
until |
string |
|
Result: agent.WaitResult
api
api.schema
No params.
Result: protocol.Schema
api.snapshot
No params.
Result: runtime.APISnapshot
client
client.report
| Param |
Type |
|
budget |
integer |
|
rtt_us |
integer |
|
Result: protocol.Empty
debug
debug.pprof (pipe)
| Param |
Type |
|
profile |
string |
|
seconds |
integer |
|
Result: protocol.Empty
debug.stats
No params.
Result: runtime.Stats
environment
environment.create
Result: environment.Environment
environment.get
Result: environment.Environment
environment.list
No params.
Result: []environment.Environment
environment.remove
Result: protocol.Empty
environment.update
| Param |
Type |
|
id |
string |
|
set |
map[string]string |
|
unset |
[]string |
|
Result: environment.Environment
events
events.subscribe (pipe)
| Param |
Type |
|
types |
[]string |
|
Result: event.subscribeResult
layout
layout.apply
Result: pane.ApplyResult
layout.export
| Param |
Type |
|
environments |
[]string |
|
Result: pane.LayoutSpec
No params.
Result: []metadata.Entry
| Param |
Type |
|
clear |
boolean |
|
environment |
string |
|
pane |
string |
|
source |
string |
|
title |
string |
|
tokens |
map[string]string |
|
ttl |
integer |
nanoseconds |
Result: metadata.Entry
pane
pane.close
Result: protocol.Empty
pane.focus
| Param |
Type |
|
direction |
string |
|
id |
string |
|
Result: pane.Pane
pane.get
Result: pane.Pane
| Param |
Type |
|
data |
string |
|
id |
string |
|
Result: protocol.Empty
pane.list
| Param |
Type |
|
environment_id |
string |
|
tab_id |
string |
|
Result: []pane.Pane
pane.move
| Param |
Type |
|
direction |
string |
|
environment_id |
string |
|
pane |
string |
|
tab_id |
string |
|
target |
string |
|
Result: pane.Pane
| Param |
Type |
|
height_pct |
integer |
|
spec |
pane.Spec |
|
tab_id |
string |
|
width_pct |
integer |
|
Result: pane.Pane
pane.read
| Param |
Type |
|
ansi |
boolean |
|
id |
string |
|
lines |
integer |
|
source |
string |
|
Result: []string
pane.rename
| Param |
Type |
|
id |
string |
|
name |
string |
|
Result: pane.Pane
pane.resize
| Param |
Type |
|
cells |
integer |
|
direction |
string |
|
id |
string |
|
Result: pane.Pane
pane.run
| Param |
Type |
|
command |
string |
|
id |
string |
|
Result: protocol.Empty
pane.send_keys
| Param |
Type |
|
id |
string |
|
keys |
[]string |
|
Result: protocol.Empty
pane.send_text
| Param |
Type |
|
id |
string |
|
paste |
boolean |
|
text |
string |
|
Result: protocol.Empty
pane.split
| Param |
Type |
|
direction |
string |
|
focus |
boolean |
|
pane |
string |
|
ratio |
number |
|
spec |
pane.Spec |
|
tab_id |
string |
|
Result: pane.Pane
pane.swap
| Param |
Type |
|
id |
string |
|
with |
string |
|
Result: protocol.Empty
pane.wait_output
| Param |
Type |
|
anywhere |
boolean |
|
id |
string |
|
pattern |
string |
|
timeout_ms |
integer |
|
Result: map[string]string
pane.zoom
| Param |
Type |
|
id |
string |
|
on |
boolean |
|
Result: pane.Pane
plugin
plugin.list
No params.
Result: []plugin.Status
plugin.reload
No params.
Result: []plugin.Status
plugin.run
| Param |
Type |
|
action |
string |
|
environment |
string |
|
pane |
string |
|
plugin |
string |
|
tab |
string |
|
Result: plugin.Result
process
process.get
Result: process.Process
process.list
| Param |
Type |
|
environment_id |
string |
|
Result: []process.Process
process.logs
| Param |
Type |
|
follow |
boolean |
|
id |
string |
|
stream |
string |
|
tail |
integer |
|
Result: process.logsResult
process.logs.stream
No params.
process.start
| Param |
Type |
|
args |
[]string |
|
command |
string |
|
cwd |
string |
|
env |
map[string]string |
|
environment_id |
string |
|
height |
integer |
|
terminal |
boolean |
|
width |
integer |
|
Result: process.Process
process.stop
Result: protocol.Empty
runtime
runtime.gc
| Param |
Type |
|
dry_run |
boolean |
|
older_than |
integer |
nanoseconds |
Result: persist.GCReport
runtime.ping
No params.
Result: map[string]boolean
runtime.shutdown
No params.
runtime.status
No params.
Result: runtime.Snapshot
session
session.restore
| Param |
Type |
|
resume_agents |
boolean |
|
Result: persist.RestoreReport
session.save
No params.
Result: persist.SaveResult
tab
tab.close
Result: protocol.Empty
tab.create
| Param |
Type |
|
environment_id |
string |
|
name |
string |
|
pane |
pane.Spec |
|
Result: map[string]any
tab.focus
Result: pane.Tab
tab.get
Result: pane.Tab
tab.list
| Param |
Type |
|
environment_id |
string |
|
tab_id |
string |
|
Result: []pane.Tab
tab.rename
| Param |
Type |
|
id |
string |
|
name |
string |
|
Result: pane.Tab
tab.resize
| Param |
Type |
|
height |
integer |
|
id |
string |
|
width |
integer |
|
Result: pane.Tab
terminal
terminal.attach (pipe)
| Param |
Type |
|
height |
integer |
|
process_id |
string |
|
width |
integer |
|
Result: terminal.viewResult
terminal.frames (pipe)
| Param |
Type |
|
height |
integer |
|
process_id |
string |
|
width |
integer |
|
Result: terminal.viewResult
| Param |
Type |
|
data |
string |
|
process_id |
string |
|
view_id |
string |
|
Result: protocol.Empty
terminal.resize
| Param |
Type |
|
height |
integer |
|
process_id |
string |
|
view_id |
string |
|
width |
integer |
|
Result: protocol.Empty
terminal.snapshot
| Param |
Type |
|
ansi |
boolean |
|
process_id |
string |
|
scrollback |
integer |
|
Result: terminal.SnapshotResult
worktree
worktree.create
| Param |
Type |
|
base |
string |
|
branch |
string |
|
env |
map[string]string |
|
id |
string |
|
repo |
string |
|
Result: environment.Environment
worktree.list
Result: []runtime.WorktreeInfo
worktree.open
| Param |
Type |
|
env |
map[string]string |
|
id |
string |
|
path |
string |
|
Result: environment.Environment
worktree.remove
| Param |
Type |
|
force |
boolean |
|
id |
string |
|
path |
string |
|
Result: protocol.Empty
Types
agent.Agent
| Field |
Type |
|
completion_seq |
integer |
|
environment_id |
string |
|
id |
string |
|
kind |
string |
|
last_output |
string |
|
name |
string |
|
pane_id |
string |
|
pid |
integer |
|
reason |
string |
|
session_id |
string |
|
since |
string |
|
source |
string |
|
state |
string |
|
state_seq |
integer |
|
tab_id |
string |
|
agent.Detect
| Field |
Type |
|
args_regex |
string |
|
process |
[]string |
|
agent.Explanation
agent.KeysParams
| Field |
Type |
|
id |
string |
|
keys |
[]string |
|
agent.ListResult
agent.Manifest
agent.Matcher
agent.PromptParams
| Field |
Type |
|
id |
string |
|
read |
integer |
|
stall_timeout_ms |
integer |
|
start_timeout_ms |
integer |
|
text |
string |
|
timeout_ms |
integer |
|
until |
string |
|
wait |
boolean |
|
agent.PromptResult
| Field |
Type |
|
agent |
agent.Agent |
|
outcome |
string |
|
output |
[]string |
|
agent.ReadParams
| Field |
Type |
|
ansi |
boolean |
|
id |
string |
|
lines |
integer |
|
source |
string |
|
agent.ReloadResult
| Field |
Type |
|
manifests |
[]string |
|
warnings |
[]string |
|
agent.ReportState
| Field |
Type |
|
message |
string |
|
session_id |
string |
|
state |
string |
|
ttl |
integer |
nanoseconds |
until |
string |
|
agent.Resume
| Field |
Type |
|
args |
[]string |
|
last |
[]string |
|
agent.Rollups
| Field |
Type |
|
environments |
map[string]string |
|
session |
string |
|
tabs |
map[string]string |
|
agent.Rule
| Field |
Type |
|
description |
string |
|
match |
agent.Matcher |
|
priority |
integer |
|
region |
string |
|
state |
string |
|
agent.Start
| Field |
Type |
|
command |
[]string |
|
submit |
string |
|
submit_delay_ms |
integer |
|
agent.Verdict
| Field |
Type |
|
description |
string |
|
region |
string |
|
rule |
integer |
|
state |
string |
|
text |
string |
|
agent.WaitParams
| Field |
Type |
|
after |
integer |
|
id |
string |
|
stall_ms |
integer |
|
timeout_ms |
integer |
|
until |
string |
|
agent.WaitResult
agent.idParams
agent.listParams
agent.reportParams
| Field |
Type |
|
id |
string |
|
message |
string |
|
session_id |
string |
|
state |
string |
|
ttl_ms |
integer |
|
environment.CreateRequest
environment.Environment
| Field |
Type |
|
created_at |
string |
|
env |
map[string]string |
|
git |
git.Status |
|
id |
string |
|
managed |
boolean |
|
name |
string |
|
path |
string |
|
schema |
integer |
|
status |
string |
|
worktree |
environment.Worktree |
|
environment.UpdateRequest
| Field |
Type |
|
id |
string |
|
set |
map[string]string |
|
unset |
[]string |
|
environment.Worktree
| Field |
Type |
|
branch |
string |
|
repo |
string |
|
environment.idParams
event.subscribeParams
| Field |
Type |
|
types |
[]string |
|
event.subscribeResult
git.Status
| Field |
Type |
|
ahead |
integer |
|
behind |
integer |
|
branch |
string |
|
conflicts |
integer |
|
detached |
boolean |
|
head |
string |
|
modified |
integer |
|
root |
string |
|
staged |
integer |
|
untracked |
integer |
|
upstream |
string |
|
layout.Node
layout.Rect
| Field |
Type |
|
H |
integer |
|
W |
integer |
|
X |
integer |
|
Y |
integer |
|
metadata.Entry
| Field |
Type |
|
environment |
string |
|
pane |
string |
|
title |
string |
|
title_until |
string |
|
tokens |
[]metadata.Token |
|
| Field |
Type |
|
clear |
boolean |
|
environment |
string |
|
pane |
string |
|
source |
string |
|
title |
string |
|
tokens |
map[string]string |
|
ttl |
integer |
nanoseconds |
| Field |
Type |
|
key |
string |
|
source |
string |
|
text |
string |
|
until |
string |
|
pane.ApplyResult
| Field |
Type |
|
created_environments |
[]string |
|
panes |
integer |
|
tabs |
[]pane.Tab |
|
pane.CreateTabRequest
| Field |
Type |
|
environment_id |
string |
|
name |
string |
|
pane |
pane.Spec |
|
pane.EnvironmentSpec
| Field |
Type |
|
env |
map[string]string |
|
id |
string |
|
root |
string |
|
tabs |
[]pane.TabSpec |
|
pane.LayoutSpec
pane.MoveRequest
| Field |
Type |
|
direction |
string |
|
environment_id |
string |
|
pane |
string |
|
tab_id |
string |
|
target |
string |
|
pane.NodeSpec
pane.Pane
| Field |
Type |
|
created_at |
string |
|
environment_id |
string |
|
focused |
boolean |
|
id |
string |
|
name |
string |
|
popup |
boolean |
|
process |
process.Process |
|
process_id |
string |
|
rect |
layout.Rect |
|
tab_id |
string |
|
zoomed |
boolean |
|
| Field |
Type |
|
height_pct |
integer |
|
pane |
string |
|
width_pct |
integer |
|
| Field |
Type |
|
height_pct |
integer |
|
spec |
pane.Spec |
|
tab_id |
string |
|
width_pct |
integer |
|
pane.Spec
| Field |
Type |
|
command |
[]string |
|
cwd |
string |
|
env |
map[string]string |
|
name |
string |
|
pane.SplitRequest
| Field |
Type |
|
direction |
string |
|
focus |
boolean |
|
pane |
string |
|
ratio |
number |
|
spec |
pane.Spec |
|
tab_id |
string |
|
pane.Tab
| Field |
Type |
|
active |
boolean |
|
created_at |
string |
|
environment_id |
string |
|
focused |
string |
|
height |
integer |
|
id |
string |
|
layout |
layout.Node |
|
name |
string |
|
popups |
[]pane.Popup |
|
width |
integer |
|
zoomed |
string |
|
pane.TabSpec
pane.exportParams
| Field |
Type |
|
environments |
[]string |
|
pane.focusParams
| Field |
Type |
|
direction |
string |
|
id |
string |
|
pane.idParams
| Field |
Type |
|
data |
string |
|
id |
string |
|
pane.keysParams
| Field |
Type |
|
id |
string |
|
keys |
[]string |
|
pane.listParams
| Field |
Type |
|
environment_id |
string |
|
tab_id |
string |
|
pane.paneResizeParams
| Field |
Type |
|
cells |
integer |
|
direction |
string |
|
id |
string |
|
pane.readParams
| Field |
Type |
|
ansi |
boolean |
|
id |
string |
|
lines |
integer |
|
source |
string |
|
pane.renameParams
| Field |
Type |
|
id |
string |
|
name |
string |
|
pane.runParams
| Field |
Type |
|
command |
string |
|
id |
string |
|
pane.swapParams
| Field |
Type |
|
id |
string |
|
with |
string |
|
pane.tabResizeParams
| Field |
Type |
|
height |
integer |
|
id |
string |
|
width |
integer |
|
pane.textParams
| Field |
Type |
|
id |
string |
|
paste |
boolean |
|
text |
string |
|
pane.waitParams
| Field |
Type |
|
anywhere |
boolean |
|
id |
string |
|
pattern |
string |
|
timeout_ms |
integer |
|
pane.zoomParams
| Field |
Type |
|
id |
string |
|
on |
boolean |
|
persist.GCReport
| Field |
Type |
|
bytes |
integer |
|
dry_run |
boolean |
|
files |
[]string |
|
processes |
[]string |
|
persist.GCRequest
| Field |
Type |
|
dry_run |
boolean |
|
older_than |
integer |
nanoseconds |
persist.RestoreReport
persist.RestoreRequest
| Field |
Type |
|
resume_agents |
boolean |
|
persist.RestoredPane
| Field |
Type |
|
agent |
string |
|
command |
[]string |
|
cwd |
string |
|
environment |
string |
|
error |
string |
|
pane |
string |
|
process_id |
string |
|
resumed |
string |
|
typed |
string |
|
persist.SaveResult
| Field |
Type |
|
path |
string |
|
written |
boolean |
|
plugin.Action
| Field |
Type |
|
command |
[]string |
|
id |
string |
|
timeout |
string |
|
title |
string |
|
plugin.Event
| Field |
Type |
|
command |
[]string |
|
on |
string |
|
timeout |
string |
|
plugin.Manifest
plugin.Result
| Field |
Type |
|
exit_code |
integer |
|
output |
string |
|
plugin.Startup
| Field |
Type |
|
command |
[]string |
|
restart |
boolean |
|
plugin.Status
| Field |
Type |
|
commit |
string |
|
dir |
string |
|
enabled |
boolean |
|
id |
string |
|
installed_at |
string |
|
last_error |
string |
|
linked |
boolean |
|
manifest |
plugin.Manifest |
|
problem |
string |
|
ref |
string |
|
running |
integer |
|
source |
string |
|
process.LogsRequest
| Field |
Type |
|
follow |
boolean |
|
id |
string |
|
stream |
string |
|
tail |
integer |
|
process.Process
| Field |
Type |
|
args |
[]string |
|
command |
string |
|
ended_at |
string |
|
env |
map[string]string |
|
environment_id |
string |
|
exit_code |
integer |
|
id |
string |
|
lost |
boolean |
|
pid |
integer |
|
started_at |
string |
|
status |
string |
|
terminal |
boolean |
|
working_dir |
string |
|
process.StartRequest
| Field |
Type |
|
args |
[]string |
|
command |
string |
|
cwd |
string |
|
env |
map[string]string |
|
environment_id |
string |
|
height |
integer |
|
terminal |
boolean |
|
width |
integer |
|
process.idParams
process.listParams
| Field |
Type |
|
environment_id |
string |
|
process.logsResult
| Field |
Type |
|
logs |
string |
|
truncated |
boolean |
|
protocol.Empty
An object.
protocol.LinkReport
| Field |
Type |
|
budget |
integer |
|
rtt_us |
integer |
|
protocol.MethodSchema
| Field |
Type |
|
name |
string |
|
params |
any |
|
pipe |
boolean |
|
result |
any |
|
protocol.Schema
runtime.APISnapshot
runtime.AgentStartRequest
| Field |
Type |
|
args |
[]string |
|
base |
string |
|
env |
map[string]string |
|
environment_id |
string |
|
kind |
string |
|
name |
string |
|
worktree |
string |
|
runtime.AgentStarted
runtime.PluginRunRequest
| Field |
Type |
|
action |
string |
|
environment |
string |
|
pane |
string |
|
plugin |
string |
|
tab |
string |
|
runtime.PprofRequest
| Field |
Type |
|
profile |
string |
|
seconds |
integer |
|
runtime.Snapshot
| Field |
Type |
|
agents_survive_restart |
boolean |
|
api_level |
integer |
|
pid |
integer |
|
protocol_version |
string |
|
session |
string |
|
socket |
string |
|
started_at |
string |
|
status |
string |
|
version |
string |
|
runtime.Stats
| Field |
Type |
|
goroutines |
integer |
|
heap_alloc |
integer |
|
heap_sys |
integer |
|
num_gc |
integer |
|
open_fds |
integer |
|
started_at |
string |
|
uptime_seconds |
number |
|
runtime.WorktreeCreateRequest
| Field |
Type |
|
base |
string |
|
branch |
string |
|
env |
map[string]string |
|
id |
string |
|
repo |
string |
|
runtime.WorktreeInfo
| Field |
Type |
|
bare |
boolean |
|
branch |
string |
|
detached |
boolean |
|
environments |
[]string |
|
head |
string |
|
locked |
boolean |
|
main |
boolean |
|
path |
string |
|
runtime.WorktreeOpenRequest
| Field |
Type |
|
env |
map[string]string |
|
id |
string |
|
path |
string |
|
runtime.WorktreeRemoveRequest
| Field |
Type |
|
force |
boolean |
|
id |
string |
|
path |
string |
|
runtime.agentIDParams
runtime.agentRenameParams
| Field |
Type |
|
id |
string |
|
name |
string |
|
runtime.worktreeListParams
terminal.SnapshotResult
| Field |
Type |
|
alt_screen |
boolean |
|
cursor |
vt.Cursor |
|
height |
integer |
|
lines |
[]string |
|
scrollback |
[]string |
|
title |
string |
|
width |
integer |
|
| Field |
Type |
|
data |
string |
|
process_id |
string |
|
view_id |
string |
|
terminal.resizeParams
| Field |
Type |
|
height |
integer |
|
process_id |
string |
|
view_id |
string |
|
width |
integer |
|
terminal.snapshotParams
| Field |
Type |
|
ansi |
boolean |
|
process_id |
string |
|
scrollback |
integer |
|
terminal.viewParams
| Field |
Type |
|
height |
integer |
|
process_id |
string |
|
width |
integer |
|
terminal.viewResult
| Field |
Type |
|
height |
integer |
|
view_id |
string |
|
width |
integer |
|
vt.Cursor
| Field |
Type |
|
Blink |
boolean |
|
Hidden |
boolean |
|
Shape |
integer |
|
X |
integer |
|
Y |
integer |
|