@hivey/cli 0.0.0-stage → 0.9.36
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +235 -2
- package/bin/hivey.js +98 -0
- package/native/darwin-arm64/hivey +0 -0
- package/package.json +36 -4
- package/platforms.json +3 -0
- package/repo/LICENSE +201 -0
- package/repo/NOTICE +18 -0
- package/repo/README.md +148 -0
- package/repo/install.sh +365 -0
- package/repo/pets/README.md +25 -0
- package/repo/pets/hivey-dot/CLAUDE.md +55 -0
- package/repo/pets/hivey-dot/build.sh +34 -0
- package/repo/pets/hivey-dot/main.swift +750 -0
- package/repo/pets/hivey-h/CLAUDE.md +75 -0
- package/repo/pets/hivey-h/build.sh +34 -0
- package/repo/pets/hivey-h/main.swift +739 -0
- package/repo/pets/hivey-prompt/CLAUDE.md +59 -0
- package/repo/pets/hivey-prompt/build.sh +34 -0
- package/repo/pets/hivey-prompt/main.swift +691 -0
- package/repo/pets/pet.py +288 -0
- package/repo/pets/shared/HiveyWatch.swift +437 -0
- package/repo/pets/test_pet.py +122 -0
- package/repo/plugins/README.md +108 -0
- package/repo/plugins/agent-creator/herdr-plugin.toml +17 -0
- package/repo/plugins/dashboard/dashboard.py +507 -0
- package/repo/plugins/dashboard/herdr-plugin.toml +14 -0
- package/repo/plugins/dashboard/test_dashboard.py +134 -0
- package/repo/plugins/github/github.py +261 -0
- package/repo/plugins/github/herdr-plugin.toml +14 -0
- package/repo/plugins/github/test_github.py +49 -0
- package/repo/plugins/skills/herdr-plugin.toml +11 -0
- package/repo/plugins/skills/skills.md +41 -0
- package/repo/plugins/slack-relay/connect.py +198 -0
- package/repo/plugins/slack-relay/create_channel.py +134 -0
- package/repo/plugins/slack-relay/herdr-plugin.toml +15 -0
- package/repo/plugins/slack-relay/relay.py +401 -0
- package/repo/plugins/slack-relay/slack-app-manifest.json +30 -0
- package/repo/plugins/slack-relay/test_connect.py +66 -0
- package/repo/plugins/slack-relay/test_create_channel.py +61 -0
- package/repo/plugins/slack-relay/test_relay.py +254 -0
- package/repo/plugins/swarm-creator/herdr-plugin.toml +17 -0
- package/repo/plugins/swarm-watcher/dashboard.py +333 -0
- package/repo/plugins/swarm-watcher/herdr-plugin.toml +16 -0
- package/repo/plugins/swarm-watcher/usage.py +129 -0
- package/repo/plugins/swarm-watcher/watcher.py +191 -0
- package/repo/plugins/team-template/herdr-plugin.toml +15 -0
- package/repo/plugins/team-template/setup.py +211 -0
- package/repo/plugins/team-template/test_setup.py +73 -0
- package/repo/plugins/tts/herdr-plugin.toml +15 -0
- package/repo/skills/herdr/SKILL.md +214 -0
- package/repo/skills/hivey/SKILL.md +322 -0
- package/repo/skills/hivey/scripts/handoff.py +27 -0
- package/repo/skills/hivey/scripts/new_wiki.py +143 -0
- package/repo/skills/hivey-agent-creator/SKILL.md +303 -0
- package/repo/skills/hivey-agent-creator/references/agent-claude-md.md +256 -0
- package/repo/skills/hivey-agent-creator/references/global-guidelines.md +67 -0
- package/repo/skills/hivey-agent-creator/references/reviewer-agent.md +35 -0
- package/repo/skills/hivey-agent-creator/scripts/agent_context.py +76 -0
- package/repo/skills/hivey-agent-creator/scripts/agent_gate.py +78 -0
- package/repo/skills/hivey-agent-creator/scripts/setup_agent.py +288 -0
- package/repo/skills/hivey-agy/SKILL.md +123 -0
- package/repo/skills/hivey-agy/references/gemini-prompting.md +134 -0
- package/repo/skills/hivey-agy/scripts/agy_run.py +146 -0
- package/repo/skills/hivey-codex/SKILL.md +66 -0
- package/repo/skills/hivey-context7/SKILL.md +56 -0
- package/repo/skills/hivey-create-wiki/SKILL.md +329 -0
- package/repo/skills/hivey-grok/SKILL.md +101 -0
- package/repo/skills/hivey-grok/scripts/grok_run.py +139 -0
- package/repo/skills/hivey-swarm-creator/SKILL.md +384 -0
- package/repo/skills/hivey-swarm-creator/references/agent-claude-md.md +313 -0
- package/repo/skills/hivey-swarm-creator/references/archify-report.md +24 -0
- package/repo/skills/hivey-swarm-creator/references/dashboard.md +46 -0
- package/repo/skills/hivey-swarm-creator/references/retrospective.md +23 -0
- package/repo/skills/hivey-swarm-creator/references/shared-rules.md +39 -0
- package/repo/skills/hivey-swarm-creator/references/wiki-memory.md +30 -0
- package/repo/skills/hivey-swarm-creator/scripts/setup_agent.py +76 -0
- package/repo/skills/hivey-swarm-creator/scripts/shared_rules.py +50 -0
- package/repo/skills/hivey-swarm-creator/scripts/swarm_tasks.py +171 -0
- package/repo/skills/hivey-wiki-ingest/SKILL.md +45 -0
- package/repo/skills/hivey-wiki-lint/SKILL.md +38 -0
- package/repo/skills/hivey-wiki-list/SKILL.md +46 -0
- package/repo/skills/hivey-wiki-log/SKILL.md +45 -0
- package/repo/skills/hivey-wiki-query/SKILL.md +44 -0
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: herdr
|
|
3
|
+
description: "Control Herdr, a terminal multiplexer for coding agents. Use only when the user explicitly mentions Herdr or asks to use Herdr to inspect or control panes, tabs, workspaces, commands, or another agent. Do not use merely because a task could benefit from a background terminal, delegation, or parallel work. Requires HERDR_ENV=1."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Herdr
|
|
7
|
+
|
|
8
|
+
Herdr organizes terminals into workspaces, tabs, and panes, recognizes coding agents running inside panes, and exposes the current session through the `herdr` CLI.
|
|
9
|
+
|
|
10
|
+
Before issuing any control command, verify that this agent is running inside a Herdr-managed pane:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
test "${HERDR_ENV:-}" = 1
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
If the check fails, say that you are not running inside Herdr and stop. Do not inspect or control the focused Herdr session from outside Herdr.
|
|
17
|
+
|
|
18
|
+
When the check passes, the `herdr` binary in `PATH` talks to the current session. Use it to inspect neighboring work, create terminal layout, start agents and commands, read output, and wait for state changes.
|
|
19
|
+
|
|
20
|
+
## Learn the current CLI
|
|
21
|
+
|
|
22
|
+
The installed binary is the authority for command syntax. Start with:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
herdr --help
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Then print the relevant command group by running the group without a subcommand:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
herdr agent
|
|
32
|
+
herdr pane
|
|
33
|
+
herdr workspace
|
|
34
|
+
herdr tab
|
|
35
|
+
herdr worktree
|
|
36
|
+
herdr terminal
|
|
37
|
+
herdr notification
|
|
38
|
+
herdr integration
|
|
39
|
+
herdr session
|
|
40
|
+
herdr machine
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Do not run bare `herdr` for discovery; it launches or attaches the TUI. Do not probe a mutating nested command by omitting arguments. Commands such as `herdr workspace create` are valid with defaults and will execute.
|
|
44
|
+
|
|
45
|
+
Most control commands return JSON. Read identifiers and state from those responses instead of predicting them.
|
|
46
|
+
|
|
47
|
+
## Understand layout, panes, and agents
|
|
48
|
+
|
|
49
|
+
Choose the primitive that matches the job:
|
|
50
|
+
|
|
51
|
+
- Workspace, tab, and pane topology organize terminal locations.
|
|
52
|
+
- Pane commands control raw terminals, shells, tests, servers, input, and output.
|
|
53
|
+
- Agent commands control the recognized coding agent currently occupying a pane.
|
|
54
|
+
|
|
55
|
+
A pane exists whether or not it contains an agent. `agent start` requires an existing available shell pane and never creates, splits, or moves layout. Use pane commands for ordinary processes. Use agent commands when Herdr must validate agent identity or interpret `idle`, `working`, `blocked`, `done`, and `unknown` lifecycle states.
|
|
56
|
+
|
|
57
|
+
Agent commands accept either a unique live agent name or the pane ID currently hosting that agent. They do not accept terminal IDs or bare agent-kind labels. Names must match `[a-z][a-z0-9_-]{0,31}` and be unique among live agents. A name follows the current pane occupant and is cleared when that agent exits, is released, or is replaced.
|
|
58
|
+
|
|
59
|
+
`idle` and `done` both mean the agent is ready for input. The CLI/API uses the server's seen state to distinguish them; explicit focus commands mark the target seen, while reads do not. Each TUI client tracks viewed completions independently, so its Done badge can differ from the CLI or another client's badge. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify it confidently; it does not prove completion.
|
|
60
|
+
|
|
61
|
+
## Use IDs and caller context
|
|
62
|
+
|
|
63
|
+
Public IDs are opaque stable handles:
|
|
64
|
+
|
|
65
|
+
- workspace: `w1`
|
|
66
|
+
- tab: `w1:t1`
|
|
67
|
+
- pane: `w1:p1`
|
|
68
|
+
|
|
69
|
+
Closed tab and pane IDs are not reused. A pane moved into another workspace receives a new workspace-qualified pane ID. After `pane move`, continue with `.result.move_result.pane.pane_id` or the live agent name. The old value is reported as `.result.move_result.previous_pane_id`; only the moved process's inherited caller context keeps resolving that old ID, so do not use it as a general agent target.
|
|
70
|
+
|
|
71
|
+
Herdr injects the caller's context into each managed pane:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Prefer `--current` when a pane command should target the calling pane. An omitted `pane split` target uses the calling pane when `HERDR_PANE_ID` is available, otherwise the focused pane. Other commands may use the UI-focused pane, which can belong to the user or another client.
|
|
78
|
+
|
|
79
|
+
Discover live state with:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
herdr workspace list
|
|
83
|
+
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
|
|
84
|
+
herdr pane current --current
|
|
85
|
+
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
|
|
86
|
+
herdr agent list
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Creation responses expose the IDs to use next. `workspace create` returns `.result.workspace`, `.result.tab`, and `.result.root_pane`. `tab create` returns `.result.tab` and `.result.root_pane`. `pane split` returns the new pane as `.result.pane`.
|
|
90
|
+
|
|
91
|
+
IDs and live agent names are scoped to one server. Two saved SSH machines can both have `w1:p1` or an agent named `reviewer`. Selecting a machine in the TUI does not retarget commands running in your pane: without `--machine`, they still use the inherited session and socket context.
|
|
92
|
+
|
|
93
|
+
To control a saved SSH machine, use the same global prefix for discovery and every later command:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
herdr --machine <label-or-id> agent list
|
|
97
|
+
herdr --machine <label-or-id> pane list
|
|
98
|
+
herdr --machine <label-or-id> agent prompt <remote-agent-name> "Reply with your current status." --wait --timeout 120000
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The selector must be an enabled saved profile ID or a unique, case-sensitive label, not an arbitrary SSH hostname. Commands use that profile's remote session without an open TUI. Do not combine `--machine` with `--session` or `--remote`. Discover IDs on that machine; inherited local IDs and `--current` do not identify remote panes.
|
|
102
|
+
|
|
103
|
+
Both installations must support machine API forwarding, and the remote server must already be running and API-compatible. Forwarding never installs, starts, or restarts a server and never falls back to Local. Local configuration, session management, installation commands, and interactive attachment are not forwarded. Remote worktree paths must be absolute, `~`, or start with `~/`; plugin link paths must be absolute. A connection failure does not prove a mutation was not applied: inspect remote state before retrying.
|
|
104
|
+
|
|
105
|
+
`herdr machine list` lists saved connection profiles, not a cross-machine pane inventory; add `--json` for scripts. Only add, remove, enable, or disable profiles when the user asks. Removing a profile disconnects the client but does not stop remote sessions. Interactive `machine add` discovers running remote sessions and may ask the user to pick one; non-interactive setup uses the remote default session unless `--remote-session` is explicitly supplied. Use `herdr machine status [<label-or-id>] --json` to diagnose a failing machine. `herdr machine reconnect` needs the user to complete SSH authentication in their terminal; do not run it for them. Setup asks before stopping an incompatible server and defaults to No; do not approve replacement without the user's consent. Experimental handoff is not part of `machine add`.
|
|
106
|
+
|
|
107
|
+
## Start and coordinate an agent
|
|
108
|
+
|
|
109
|
+
Default to a sibling pane in the current tab and the current working directory. Do not create a workspace, tab, worktree, or different cwd unless the user explicitly requests that topology or location.
|
|
110
|
+
|
|
111
|
+
Honor a direction requested by the user. Otherwise inspect the caller pane:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
herdr pane layout --pane "$HERDR_PANE_ID"
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Split a wide pane to the right and a narrow or tall pane down. Avoid repeated same-direction splits that create unusably narrow columns or short rows. Keep the user's focus in the calling pane and explicitly preserve the caller's working directory:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
herdr pane split --current --direction right --cwd "$PWD" --no-focus
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Replace `right` with `down` when appropriate. Read the new pane ID from `.result.pane.pane_id`.
|
|
124
|
+
|
|
125
|
+
An available shell pane must be at its interactive prompt, with the shell itself in the foreground and no foreground command, editor, or agent running. Start a supported agent in that pane with a useful unique name:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
herdr agent start reviewer --kind codex --pane <returned-pane-id>
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Use the kind requested by the user. Run `herdr agent` to inspect the installed kind list and options. Pass native agent arguments only after `--`:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
A successful `agent start` returns only after Herdr detects the expected agent in the same pane and considers it ready for interactive input. If the agent is blocked during startup, the command returns `agent_not_ready` immediately but keeps the name available for `agent read` and `agent send-keys`. Wait until the agent becomes idle before prompting it. Startup defaults to a 30-second timeout.
|
|
138
|
+
|
|
139
|
+
Submit work through the agent surface:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`agent prompt` honors the pane's live bracketed-paste mode and sends text followed by encoded Enter as one ordered submission. It reports successful submission only after both have been written; that alone does not prove the agent started a turn. For Codex on Windows, Herdr sends a paste boundary before Enter so submission does not depend on prompt size. It rejects an agent already waiting at an approval or question dialog with `agent_blocked` before sending any input. Inspect the blocked UI and ask the user before answering it. For normal agent work, `--wait` is enough: it waits for the first settled `idle`, `done`, or `blocked` state. Do not repeat those defaults with `--until`.
|
|
146
|
+
|
|
147
|
+
With `--wait`, a prompt sent from a non-working state must produce observed `working` or `blocked` activity. After submission, Herdr waits up to five seconds for that activity; unrelated `idle`, `done`, or session changes do not satisfy this gate. It returns `agent_prompt_stalled` if no activity is observed, or `timeout` if the caller's timeout expires first. The caller timeout includes submission time. Without a timeout, the settled-state wait is indefinite after activity is observed. This wait tracks lifecycle state, not an individual turn; if the agent is already working, completion of the active turn may satisfy it.
|
|
148
|
+
|
|
149
|
+
Use `--until` only for a state-specific workflow, such as waiting for an already-running agent to request input:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
herdr agent wait reviewer --until blocked --timeout 120000
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Without `--until`, standalone `agent wait` uses the same settled-state defaults as `agent prompt --wait`.
|
|
156
|
+
|
|
157
|
+
Use logical keys for interactive agent UI controls:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
herdr agent send-keys reviewer esc
|
|
161
|
+
herdr agent send-keys reviewer ctrl+c
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Herdr validates all keys before writing any bytes. Read the result through the resolved agent:
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
herdr agent get reviewer
|
|
168
|
+
herdr agent read reviewer --source recent-unwrapped --lines 120
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
If a wait fails or returns `blocked`, inspect `agent get` and `agent read` before deciding what input to send. A timeout or stalled response does not prove the prompt was never delivered; do not blindly submit it again. Use the pane surface only when raw terminal control is intentional.
|
|
172
|
+
|
|
173
|
+
## Run an ordinary command in another pane
|
|
174
|
+
|
|
175
|
+
Create a sibling pane with the same geometry rule, preserve the caller's working directory, and keep user focus unchanged:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
herdr pane split --current --direction right --cwd "$PWD" --no-focus
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Read the new pane ID from `.result.pane.pane_id`, then run and inspect the command:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
herdr pane run <returned-pane-id> "just test"
|
|
185
|
+
herdr pane wait-output <returned-pane-id> --match "test result" --timeout 120000
|
|
186
|
+
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`pane run` atomically sends command text and Enter. `pane wait-output` searches the selected snapshot immediately, so output that already exists can match. Use `--match <text>` for a literal substring or `--regex <pattern>` for a Rust regular expression. Omitting `--timeout` allows an indefinite wait.
|
|
190
|
+
|
|
191
|
+
Use the read source that matches the task:
|
|
192
|
+
|
|
193
|
+
- `visible`: the currently rendered viewport.
|
|
194
|
+
- `recent`: recent rendered output, including soft wraps.
|
|
195
|
+
- `recent-unwrapped`: recent output with soft wraps joined; prefer it for logs and transcripts.
|
|
196
|
+
- `detection`: the plain-text bottom-buffer snapshot used for agent detection.
|
|
197
|
+
|
|
198
|
+
Use `--format ansi` when colors and terminal styling are evidence. Otherwise use text.
|
|
199
|
+
|
|
200
|
+
`--lines` asks Herdr for more rows from the pane's available screen and host scrollback. Alternate-screen rows do not enter ordinary host scrollback. For supported idle agents, Herdr can collect application-owned history and restore the viewport afterward, but not every application or response can be recovered this way.
|
|
201
|
+
|
|
202
|
+
If a larger recent read still does not reveal the completed response, ask the agent to write it as Markdown in a temporary directory and reply only with the file path, then read that file on the same machine. Use this only as a fallback; do not request file output in the initial prompt.
|
|
203
|
+
|
|
204
|
+
## Safety and coordination rules
|
|
205
|
+
|
|
206
|
+
- Use `--no-focus` for background work unless the user asked to switch context.
|
|
207
|
+
- Use `--current`, an explicit pane ID, or a unique agent name. Do not rely on another client's focused pane.
|
|
208
|
+
- Parse IDs from JSON responses. Do not derive them from sidebar order or examples.
|
|
209
|
+
- Do not close workspaces, tabs, panes, or sessions you did not create unless the user explicitly asked. `workspace close --group` closes the primary workspace and its linked worktree workspaces; never add it merely to bypass `workspace_group_close_required`.
|
|
210
|
+
- Use `--trust-repository` only after the user has verified the repository. It grants per-request Git trust; it is not a routine retry for a failed worktree command.
|
|
211
|
+
- Client and server versions can differ after an update. Check `herdr status` before relying on new server features. A missing method is not permission to stop or upgrade a server.
|
|
212
|
+
- Never run `herdr server stop` from an active session unless the user explicitly intends to stop the server and its pane processes.
|
|
213
|
+
- Never kill the main Herdr process. Use named test sessions for experiments that need an isolated server.
|
|
214
|
+
- CLI server errors are JSON on stderr with exit status 1. CLI syntax errors exit with status 2.
|
|
@@ -0,0 +1,322 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hivey
|
|
3
|
+
description: Operate hivey, the terminal workspace for swarms of AI agents (a herdr fork). Use when the user says hivey (or "hyver"/"hybrid" meaning hivey) and wants to start, attach, detach, close or stop hivey sessions; create, launch, inspect, pause, relaunch or message swarms; schedule master check-ins; list, install, link, enable or configure plugins/addons (Slack relay, dashboard, GitHub, watcher); or write a new hivey plugin (an addon pane or a swarm setup provider). Also for hivey troubleshooting (keys, click-to-master, missing features after an upgrade).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
> Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
|
|
7
|
+
> It holds this machine's own additions; hivey updates never touch it, so put local changes
|
|
8
|
+
> there, never here.
|
|
9
|
+
|
|
10
|
+
# hivey
|
|
11
|
+
|
|
12
|
+
hivey runs swarms of coding agents (Claude Code, Codex, Grok, Antigravity/Gemini `agy`): **one space per swarm, pane 1 = the master
|
|
13
|
+
(coordinator)**, a message bus between agents (`hivey msg`), addons (plugins) in the swarm's space,
|
|
14
|
+
and a "swarms" sidebar. It's a fork of herdr; every `herdr` command works as `hivey`.
|
|
15
|
+
|
|
16
|
+
- Binary: `hivey` (`~/.local/bin/hivey`). Repo: the clone hivey was installed from (`hivey update` uses it; `HIVEY_REPO` overrides)
|
|
17
|
+
(guide `docs/hivey-guide.md`, plugins `plugins/`, provider guide `docs/hivey-providers.md`).
|
|
18
|
+
- Config: `~/.config/hivey/config.toml`. Plugin configs: `hivey plugin config-dir <id>`.
|
|
19
|
+
- The original `herdr` (separate binary and server) may also be running: never touch it.
|
|
20
|
+
|
|
21
|
+
## Rules
|
|
22
|
+
|
|
23
|
+
- **Stopping a session stops its agents.** Detaching doesn't. Ask before `session stop`,
|
|
24
|
+
`server stop`, closing panes, or `swarm forget` on a swarm that is working.
|
|
25
|
+
- Prefer detach + attach. A stopped swarm comes back with `hivey swarm relaunch <slug>`
|
|
26
|
+
(agents continue their conversations).
|
|
27
|
+
- Confirm before anything outward-facing (Slack posts, GitHub repos); the GitHub addon already asks.
|
|
28
|
+
- Never run `hivey integration install` (it rewrites shared agent hooks). `hivey update` is safe
|
|
29
|
+
(builds from the user's hivey clone, hands sessions off live); `--check` pushes, so ask first.
|
|
30
|
+
- Secrets: never write tokens into files or prompts; plugins read them via `token_command`
|
|
31
|
+
(e.g. envsave). Key *names* are fine.
|
|
32
|
+
- **Machine-specific changes go in EXTRA files, never in what hivey updates.** hivey's repo,
|
|
33
|
+
skills and commands are rewritten by `hivey update`. A user's own additions for this machine
|
|
34
|
+
go in `EXTRA_AGENTS.md` in the hivey repo (next to `AGENTS.md`, git-ignored) or
|
|
35
|
+
`EXTRA_SKILL.md` in a hivey skill's folder; both are read automatically and never touched by
|
|
36
|
+
updates. When the user wants to change how hivey or a hivey skill behaves on their machine,
|
|
37
|
+
write it there.
|
|
38
|
+
- **Safety hooks** (`hivey safety on|off`, settings → safety; on by default): block destructive
|
|
39
|
+
commands, history rewrites, `curl | sh`, secret access and hand-edited lockfiles for Claude
|
|
40
|
+
Code agents. When one blocks you, ask the user; never work around it, and never turn safety
|
|
41
|
+
off yourself.
|
|
42
|
+
- **Docs: Context7 first.** For any library, framework, SDK, API, CLI or cloud service, look the
|
|
43
|
+
docs up with the `hivey-context7` skill (current docs in seconds, no MCP needed) before a web
|
|
44
|
+
search or your memory, and write the same rule into every agent brief you create.
|
|
45
|
+
- **Skills, agents and swarms you create are saved with skylls** (if `skylls --version` works):
|
|
46
|
+
look for existing ones first (`skylls --json find <words> --limit 5`, also `agents find`,
|
|
47
|
+
`swarms find`); after creating one, offer `skylls push <skill folder>`, `skylls agents push
|
|
48
|
+
<agent folder>` or `skylls swarms push <swarm folder>` and run it only with the user's yes.
|
|
49
|
+
Share (`skylls share … @user`) only when asked; never `--skip-scan`.
|
|
50
|
+
|
|
51
|
+
## Sessions: start, attach, detach, close
|
|
52
|
+
|
|
53
|
+
Each project can have its own session (server + its swarms).
|
|
54
|
+
|
|
55
|
+
| Want | Do |
|
|
56
|
+
|---|---|
|
|
57
|
+
| open hivey (default session) | `hivey` |
|
|
58
|
+
| per-project session | `hivey --session <name>` (start or attach) |
|
|
59
|
+
| list sessions | `hivey session list` |
|
|
60
|
+
| **detach** (leave, everything keeps running) | `⌥Q` or `ctrl+b` then `q` in the hivey terminal |
|
|
61
|
+
| re-attach | `hivey session attach <name>` / `hivey` |
|
|
62
|
+
| **stop** a session (agents stop too, ask first) | `hivey session stop <name>`; default: `hivey server stop` |
|
|
63
|
+
| delete a stopped session | `hivey session delete <name>` |
|
|
64
|
+
|
|
65
|
+
Target a session from outside it: `hivey --session <name> <command>` (e.g.
|
|
66
|
+
`hivey --session test-project swarm list`). Inside a hivey pane, commands go to that session.
|
|
67
|
+
|
|
68
|
+
Keys (after `hivey swarm setup`): `⌥S` swarms picker, `⌥M` master, `⌥A` all agents, `⌥I` info,
|
|
69
|
+
`⌥L` message log, `⌥F` / double-click a pane title = zoom, `⌥Q` quit. The `ctrl+b` prefix keys
|
|
70
|
+
still work. If `⌥` types symbols, the terminal must send Option as Meta (Terminal.app: Profiles →
|
|
71
|
+
Keyboard → "Use Option as Meta key"; iTerm2: Profiles → Keys → Left Option = Esc+).
|
|
72
|
+
Mouse: click a swarm in the sidebar → focuses its master; hover → info card; right-click an
|
|
73
|
+
agent → New session right/below (a second session of it beside it: `hivey swarm session <pane>`).
|
|
74
|
+
|
|
75
|
+
## Swarms
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
hivey swarm new "<task>" # the swarm creator designs + launches it (asks first)
|
|
79
|
+
hivey swarm new --agent "<task>" # one solo agent in this folder (agent creator)
|
|
80
|
+
hivey swarm providers [--default <id>] # swarm / agent creators; * = used (settings → plugins)
|
|
81
|
+
hivey skills [guide|add|find|online|providers] # new agents' skills: skylls + skills.sh (settings → skills)
|
|
82
|
+
hivey swarm list [--json] # swarms, agents, roles, states, queued messages
|
|
83
|
+
hivey swarm info [<slug>] # agents, Slack channel, vault, addons, budget, tasks…
|
|
84
|
+
hivey swarm master [<slug>] [--focus] # the master pane (focus it)
|
|
85
|
+
hivey swarm pause|resume <slug> # hold / release message delivery
|
|
86
|
+
hivey swarm relaunch <slug> [<agent>...] # restart agents (resume conversations) + dead addons
|
|
87
|
+
hivey swarm relaunch <slug> --addons-only # only reopen addons; --fresh: new conversations
|
|
88
|
+
hivey swarm register <root> | unregister <slug> # (alias import / forget; files kept)
|
|
89
|
+
hivey swarm directory [--json] # every swarm + solo agent: what it does, skills,
|
|
90
|
+
# tools, busy/idle, address (<slug>/master)
|
|
91
|
+
hivey swarm profile <slug> --description "…" --skills a,b --tools x,y # set its entry
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Lower level (what providers call): `hivey swarm launch <root> --slug S <agent>... [--models a=sonnet]
|
|
95
|
+
[--kinds b=codex,c=grok,d=agy] [--addon ID]... [--channel C0…] [--heartbeat 15m --heartbeat-task "…"]
|
|
96
|
+
[--budget-min N] [--kickoff "…"]`. Run it from the pane that should become the master.
|
|
97
|
+
Each agent runs on Claude Code unless `--kinds` (or `--kind` for `--solo`) says `codex`, `grok`
|
|
98
|
+
or `agy` (Antigravity, Gemini). They all read the CLAUDE.md you write: launch links `AGENTS.md`
|
|
99
|
+
(and `GEMINI.md` for agy) to it. Per-CLI flags: `--claude-args`, `--codex-args`, `--grok-args`,
|
|
100
|
+
`--agy-args` (defaults run them unattended). Pick the CLI per agent with the user: Claude Code
|
|
101
|
+
for most work, Codex for code review and a second opinion, Grok for X/web research, agy for
|
|
102
|
+
fast cheap tasks and image generation.
|
|
103
|
+
|
|
104
|
+
Scheduled check-ins (wake the master, or `--to AGENT`, with a task):
|
|
105
|
+
```bash
|
|
106
|
+
hivey swarm schedule add <slug> --every 30m "Check progress; unblock anyone stuck"
|
|
107
|
+
hivey swarm schedule add <slug> --at 09:00 --id morning "Morning status report to the user"
|
|
108
|
+
hivey swarm schedule list|remove|run [<slug>] [<id>]
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Messages (delivered when the target is idle; `--fyi` never wakes; `--urgent` now):
|
|
112
|
+
```bash
|
|
113
|
+
hivey msg send <agent|@all|@role:worker|@masters|<swarm>/<agent>|human> "text" [--fyi|--urgent] [--swarm S]
|
|
114
|
+
hivey msg inbox [--agent S/A] hivey msg log [--swarm S] [--limit N] hivey msg compose
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Panes/agents (herdr layer): `hivey pane list`, `hivey pane read <pane> --source visible`,
|
|
118
|
+
`hivey pane send-text <pane> "…"` + `hivey pane send-keys <pane> enter`, `hivey agent list`.
|
|
119
|
+
|
|
120
|
+
## Plugins (addons)
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
hivey plugin list # installed, enabled, source, config dir
|
|
124
|
+
hivey plugin link <dir> # a local plugin folder (edits apply on reopen)
|
|
125
|
+
hivey plugin install <owner/repo[/subdir]> [--ref R]
|
|
126
|
+
hivey plugin enable|disable|unlink|uninstall <id>
|
|
127
|
+
hivey plugin config-dir <id> # where its config.json lives
|
|
128
|
+
hivey plugin log <id> # its command logs
|
|
129
|
+
hivey swarm addon <slug> <id>[:<pane>]... # open addons in a running swarm
|
|
130
|
+
hivey swarm launch … --addon <id> # open them at launch
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Bundled in the repo's `plugins/` (linked by `install.sh` and `hivey migrate`): the eight
|
|
134
|
+
`hivey.*` ones. Check `hivey plugin list` / `hivey swarm providers` for others the user added.
|
|
135
|
+
|
|
136
|
+
| id | what |
|
|
137
|
+
|---|---|
|
|
138
|
+
| `hivey.slack-relay` | Slack ⇄ bus bridge (config `token_command`, channel per swarm) |
|
|
139
|
+
| `hivey.dashboard` | agents, states, tokens per agent, active time vs budget, tasks, messages |
|
|
140
|
+
| `hivey.github` | product + swarm repos, asks before creating anything |
|
|
141
|
+
| `hivey.team-template` | example setup provider (builder + critic); copy it |
|
|
142
|
+
| `hivey.swarm-creator` | Swarm creator: a coordinator runs the `hivey-swarm-creator` skill and designs a team for any task (always there) |
|
|
143
|
+
| `hivey.agent-creator` | Agent creator: a designer runs the `hivey-agent-creator` skill for one solo agent (always there) |
|
|
144
|
+
| `hivey.skills` | built-in skills plugin: how creators pick, find and install each agent's skills (`hivey skills guide`) |
|
|
145
|
+
| `hivey.swarm-watcher` | blocked / stopped / stalled / gone workers and time-budget alerts to the master (`hivey msg`), plus a Gantt dashboard page |
|
|
146
|
+
|
|
147
|
+
**Creating a swarm or agent: always ask the user three things first** (one question each, then
|
|
148
|
+
act on the answers):
|
|
149
|
+
1. **Name?** Suggest one from the task; normalize to `[a-z][a-z0-9-]{0,31}`. It's the one name
|
|
150
|
+
used everywhere: the swarm/agent slug (`--slug`) and its Slack channel `#<name>`. Never
|
|
151
|
+
pick a different name for either.
|
|
152
|
+
2. **Slack channel?** (see below)
|
|
153
|
+
3. **Obsidian wiki memory?** A vault where it keeps what it learns, always inside the swarm's
|
|
154
|
+
or agent's own folder: `<folder>/<slug>-wiki` (Obsidian lists vaults by folder name), so the work and its knowledge can be shared as one
|
|
155
|
+
folder. Never ask where the user's Obsidian is. Create it with the `hivey-create-wiki` skill
|
|
156
|
+
(`<slug> --in <swarm root or agent folder> [--agent <agent folder>]…`; it tailors the vault to
|
|
157
|
+
the agents' briefs), or plainly with `python3 <this skill>/scripts/new_wiki.py <slug> --root
|
|
158
|
+
<swarm root or agent folder> --agent <agent folder> [--agent …] --about "<one line>"` (a
|
|
159
|
+
team: one vault, every agent folder linked with a relative path). Do it after the agents' CLAUDE.md files exist, and tell the user the vault
|
|
160
|
+
path.
|
|
161
|
+
New vaults copy the theme and Style Settings of the vault remembered as `look_from` in
|
|
162
|
+
`~/.hivey/wiki.json` (set it once with `--look-from <their main vault>`); on first open
|
|
163
|
+
the user must click "Turn on community plugins" for the folder colors to show.
|
|
164
|
+
|
|
165
|
+
## Slack
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
hivey slack connect [--force] # once per machine, in a terminal: Slack app + bot token (hidden)
|
|
169
|
+
hivey slack status # connected? workspace, bot, missing scopes
|
|
170
|
+
hivey swarm launch … --slack # new swarm/agent with its own channel #<slug> + Slack relay
|
|
171
|
+
hivey slack add <slug> # channel for one that's already running
|
|
172
|
+
hivey home setup --slack # #hivey for the hivey agent
|
|
173
|
+
```
|
|
174
|
+
New channels invite the user (relay config `invite`: their Slack member id, set by `hivey slack
|
|
175
|
+
connect` or worked out from shared channels), so they appear in their Slack at once.
|
|
176
|
+
**Before creating a channel, check Slack is connected:** `hivey slack status`. Not connected →
|
|
177
|
+
ask the user to run `hivey slack connect` first (once; the token stays saved, and hivey, its
|
|
178
|
+
relays and the creators all use it), don't try and fail.
|
|
179
|
+
**Rule for every agent and swarm:** a Slack channel you create must be visible to the user
|
|
180
|
+
right away. Create channels only through hivey (`--slack`, `hivey slack add`, `hivey home
|
|
181
|
+
setup --slack`), which invites them; if one was made another way, make sure the user is in it
|
|
182
|
+
(`hivey slack add <slug>`) before saying it's done.
|
|
183
|
+
When creating a swarm or agent, ask the user whether it should get a Slack channel. Never ask
|
|
184
|
+
for the Slack token in chat: the user types it into `hivey slack connect`.
|
|
185
|
+
|
|
186
|
+
## Desktop pet (macOS)
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
hivey pet # chosen pet, running or not, the pets to choose from
|
|
190
|
+
hivey pet use hivey-h|hivey-dot|hivey-prompt # switch (built the first time, ~1 min)
|
|
191
|
+
hivey pet off # no pet
|
|
192
|
+
hivey pet choose # interactive picker (also ⌥P, and hivey menu → pets)
|
|
193
|
+
```
|
|
194
|
+
Clicking the pet opens a chat box: it sends `hivey msg send hivey/master "…"` (from `human`);
|
|
195
|
+
the hivey agent's `hivey msg send human` reply appears in the pet's bubble, spoken.
|
|
196
|
+
The pet shows while a hivey window is open (it appears with the first window and quits
|
|
197
|
+
~6s after the last one closes). It watches hivey (swarm starts, working, finished, needs you, messages incl. Slack) and
|
|
198
|
+
says the important ones aloud; right-click it for Switch pet / Turn off pet / Speak aloud.
|
|
199
|
+
Sources: `pets/<id>/` + `pets/shared/HiveyWatch.swift` in the hivey repo. Only switch or turn
|
|
200
|
+
it off when the user asks.
|
|
201
|
+
|
|
202
|
+
## Quiet mode
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
hivey quiet on|off # also hivey menu → quiet mode on/off; `hivey quiet`: status
|
|
206
|
+
hivey quiet schedule 22:30-6:45|off # on and off by itself every day (also settings → quiet)
|
|
207
|
+
hivey voice quiet 22-8 # or: no voice every night at those hours (voice only)
|
|
208
|
+
```
|
|
209
|
+
Voices: `hivey voice` (who speaks agents' `DONE:` summaries: tts, say or off; default the best
|
|
210
|
+
one installed). The local Kokoro voices are optional: `hivey voice install` (or picking one in
|
|
211
|
+
settings → voice, which opens the hivey.tts plugin's install tab) installs the `tts` tool.
|
|
212
|
+
While on (`~/.hivey/quiet` exists): nothing is spoken (pet, agents' summaries), hivey plays no
|
|
213
|
+
notification sounds or terminal bell, and Slack posts are held: the relay holds them and
|
|
214
|
+
send one catch-up message when it ends. Agents keep working, and Slack → agents still works.
|
|
215
|
+
The schedule (`~/.hivey/quiet.json`) is switched by the hivey server at the start and end of its
|
|
216
|
+
times (any minute); a switch by hand lasts until the next start or end. Only turn it on or off, or change the
|
|
217
|
+
schedule, when the user asks.
|
|
218
|
+
|
|
219
|
+
## The hivey agent (`hivey home`)
|
|
220
|
+
|
|
221
|
+
An always-on Claude in `~/.hivey/agent` (solo agent `hivey`, ⬢ mauve, first space): the user's
|
|
222
|
+
main way into hivey, also from Slack `#hivey` (relay addon). It uses this skill to launch and
|
|
223
|
+
check swarms and agents. While enabled, the server of its session restarts it when it's gone.
|
|
224
|
+
```bash
|
|
225
|
+
hivey home # status: running?, session, model, Slack channel
|
|
226
|
+
hivey home setup [--slack] [--model M] [--force] # create/refresh it in THIS session
|
|
227
|
+
hivey home start | enable | disable
|
|
228
|
+
hivey msg send hivey/master "…" # talk to it from anywhere
|
|
229
|
+
```
|
|
230
|
+
Settings: `~/.hivey/config.json`; its brief: `~/.hivey/agent/CLAUDE.md` (kept on setup unless
|
|
231
|
+
`--force`); hivey's config: `~/.hivey/config` → `~/.config/hivey`.
|
|
232
|
+
|
|
233
|
+
## Solo agents
|
|
234
|
+
|
|
235
|
+
A solo agent is a swarm with one member that is its own master: own space, ★ teal row in the
|
|
236
|
+
sidebar, messages, schedules and heartbeats like a master. Create one from the folder it will
|
|
237
|
+
live in: `mkdir -p <folder> && cd <folder> && hivey swarm new --agent "<task>"` (the agent
|
|
238
|
+
creator chosen in settings → plugins, else the built-in `hivey.agent-creator`). The designer
|
|
239
|
+
pane stays; close it once the agent runs. Lower level: `hivey swarm launch <folder> --slug S --solo
|
|
240
|
+
[--model M] [--kind codex|grok|agy] [--description … --skills … --tools …]`. Relaunch with
|
|
241
|
+
`hivey swarm relaunch <slug>` (new space if its pane is gone).
|
|
242
|
+
|
|
243
|
+
**Talking across swarms/agents:** only masters (and solo agents) may message another swarm,
|
|
244
|
+
`hivey msg send <slug>/master "…"`. Agents check `hivey swarm directory` first, **ask the user
|
|
245
|
+
before sending any work**, and don't disturb entries marked busy.
|
|
246
|
+
|
|
247
|
+
An addon whose process exits (e.g. `q` in the dashboard) is reopened with
|
|
248
|
+
`hivey swarm addon <slug> <id>` or `hivey swarm relaunch <slug> --addons-only`. Plugin code
|
|
249
|
+
changes apply when its pane is reopened.
|
|
250
|
+
|
|
251
|
+
## Create a new plugin
|
|
252
|
+
|
|
253
|
+
A plugin is a folder with `herdr-plugin.toml` + any program. Two kinds matter for swarms:
|
|
254
|
+
|
|
255
|
+
**1. Addon (a pane in each swarm's space):** relays, dashboards, monitors.
|
|
256
|
+
```toml
|
|
257
|
+
id = "me.my-addon"
|
|
258
|
+
name = "My addon"
|
|
259
|
+
version = "0.1.0"
|
|
260
|
+
min_herdr_version = "0.9.0"
|
|
261
|
+
platforms = ["linux", "macos"]
|
|
262
|
+
|
|
263
|
+
[[panes]]
|
|
264
|
+
id = "relay" # default entrypoint; others are opened as me.my-addon:<pane>
|
|
265
|
+
title = "my addon"
|
|
266
|
+
placement = "split"
|
|
267
|
+
command = ["sh", "-c", "exec python3 \"$HERDR_PLUGIN_ROOT/main.py\""]
|
|
268
|
+
```
|
|
269
|
+
It runs in the swarm root with `HIVEY_SWARM_ROOT`, `HIVEY_SWARM_SLUG`, `HIVEY_SWARM_CHANNEL`,
|
|
270
|
+
`HERDR_BIN_PATH`, `HERDR_PLUGIN_CONFIG_DIR`, `HERDR_PLUGIN_STATE_DIR`.
|
|
271
|
+
- Read the roster: `<root>/.swarm/agents.json`; live states: `hivey swarm list --json`.
|
|
272
|
+
- Outside → agents: `"$HERDR_BIN_PATH" msg send <to> "text" --swarm "$HIVEY_SWARM_SLUG" --from human`.
|
|
273
|
+
- Agents → outside: tail `<root>/.swarm/bus.jsonl` (`"ev":"msg"` lines; skip `copy: true`).
|
|
274
|
+
- Keep state on disk, never exit on network errors. Full contract: `plugins/README.md`.
|
|
275
|
+
|
|
276
|
+
**2. Setup provider (designs a swarm for `hivey swarm new`):** a pane with `id = "setup"`.
|
|
277
|
+
It reads `HIVEY_SETUP_TASK` / `HIVEY_SETUP_CWD`, then: design the team (confirm with the user) →
|
|
278
|
+
write `<root>/<agent>/CLAUDE.md` → `hivey swarm launch <root> --slug … <agents>` from its own pane
|
|
279
|
+
→ `hivey swarm accept-trust --pane "$HERDR_PANE_ID" &` → `exec claude …` (it becomes the master).
|
|
280
|
+
Walkthrough: `docs/hivey-providers.md`; template: `plugins/team-template/`.
|
|
281
|
+
|
|
282
|
+
Workflow for a new plugin:
|
|
283
|
+
1. Copy the closest example (`plugins/dashboard`, `plugins/slack-relay`, `plugins/team-template`)
|
|
284
|
+
to a new folder; change `id`, `name`, the pane `command`.
|
|
285
|
+
2. Unit-test the pure parts (`python3 -m unittest`), like the examples' `test_*.py`.
|
|
286
|
+
3. `hivey plugin link <dir>`, then try it on a small swarm (Haiku models, short budget):
|
|
287
|
+
`hivey swarm addon <slug> <id>` or `hivey swarm new --provider <id> "<task>"`.
|
|
288
|
+
4. Check `hivey plugin log <id>` if the pane dies.
|
|
289
|
+
|
|
290
|
+
## Troubleshooting
|
|
291
|
+
|
|
292
|
+
- **A feature is missing in one session** (no click-to-master, no swarm summary row/hover info,
|
|
293
|
+
"config.toml has unknown keys" banner): that session's server predates the binary. Compare
|
|
294
|
+
`ps -o lstart= -p <pid>` with `ls -l ~/.local/bin/hivey`; find the pid with
|
|
295
|
+
`lsof -U | grep sessions/<name>/herdr.sock`. Fix, after asking: a live handoff keeps agents
|
|
296
|
+
running: `python3 <this skill>/scripts/handoff.py <name>` (or stop + `hivey swarm relaunch`).
|
|
297
|
+
- **`ctrl+b q` / `⌥Q` don't quit:** check `[keys] detach` in config.toml; it should be
|
|
298
|
+
`["alt+q", "prefix+q"]` (rerun `hivey swarm setup`), then `hivey server reload-config`.
|
|
299
|
+
- **`⌥Q` types a symbol (œ) / hivey doesn't close:** the terminal doesn't send Option as Alt.
|
|
300
|
+
Tell the user: `ctrl+b` then `q` always works, or close the terminal tab (agents keep
|
|
301
|
+
running); to fix ⌥ keys set "Use Option as Meta" (Terminal.app Profiles → Keyboard; iTerm2
|
|
302
|
+
Left Option = Esc+; Ghostty `macos-option-as-alt = true`).
|
|
303
|
+
- **The desktop pet doesn't leave:** a hivey window is still open. `ls ~/.hivey/windows` lists
|
|
304
|
+
them (one file per window, named by pid; `ps -o tty=,command= -p <pid>` shows the terminal).
|
|
305
|
+
The pet quits ~6s after the last one closes and comes back with the next `hivey`.
|
|
306
|
+
- **Agent shows blocked:** it's waiting on a dialog: `hivey pane read <pane> --source visible`.
|
|
307
|
+
- **Messages not delivered:** `hivey swarm list` (✉ queued), is the swarm paused?
|
|
308
|
+
`hivey msg log --swarm <slug>`.
|
|
309
|
+
- **Update this skill:** `hivey skill install` (it ships inside the hivey binary, with the
|
|
310
|
+
`hivey-*` skills next to it, in `~/.claude/skills/` for Claude Code and `~/.agents/skills/`
|
|
311
|
+
for Codex: `hivey-create-wiki` and the wiki skills hivey-wiki-ingest, hivey-wiki-query,
|
|
312
|
+
hivey-wiki-lint, hivey-wiki-log, hivey-wiki-list (`/name` in Claude Code, `$name` in Codex);
|
|
313
|
+
source `skills/hivey*/` in the repo).
|
|
314
|
+
- **Migrate an older install:** `hivey migrate` (`--dry-run` to preview; `./install.sh` runs
|
|
315
|
+
it, `hivey update` doesn't: run it yourself after an update): the hivey-* skills; old copies they replaced (wiki-ingest, …,
|
|
316
|
+
agents-create-wiki, the old hivey-wiki-* commands, hivey skills in `~/.codex/skills`) moved to
|
|
317
|
+
`~/.hivey/old/`; wikis `<folder>/obsidian/` → `<folder>/<name>-wiki/`
|
|
318
|
+
with every CLAUDE.md, `~/Obsidian` link and Obsidian's vault list repointed (quit Obsidian first).
|
|
319
|
+
- **Install / update hivey:** first install from a clone: `./install.sh`. Update: `hivey update`
|
|
320
|
+
(latest hivey and its skills, installed, running sessions handed off live; prints old → new
|
|
321
|
+
version), then `hivey migrate` when you choose (`HIVEY_UPDATE_MIGRATE=1 hivey update` does both).
|
|
322
|
+
Maintainer: `hivey update --check` (merges herdr, tests, asks before push + install).
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Live-handoff a hivey session's server to the installed binary; panes and agents keep running.
|
|
3
|
+
|
|
4
|
+
usage: handoff.py [<session>] (default session when omitted)
|
|
5
|
+
"""
|
|
6
|
+
import json
|
|
7
|
+
import socket
|
|
8
|
+
import sys
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
name = sys.argv[1] if len(sys.argv) > 1 else "default"
|
|
12
|
+
base = Path.home() / ".config" / "hivey"
|
|
13
|
+
sock_path = base / "herdr.sock" if name == "default" else base / "sessions" / name / "herdr.sock"
|
|
14
|
+
if not sock_path.exists():
|
|
15
|
+
sys.exit(f"no running session {name!r} ({sock_path})")
|
|
16
|
+
|
|
17
|
+
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
|
18
|
+
s.settimeout(30)
|
|
19
|
+
s.connect(str(sock_path))
|
|
20
|
+
s.sendall((json.dumps({"id": "hivey:handoff", "method": "server.live_handoff", "params": {}}) + "\n").encode())
|
|
21
|
+
reply = b""
|
|
22
|
+
while not reply.endswith(b"\n"):
|
|
23
|
+
chunk = s.recv(65536)
|
|
24
|
+
if not chunk:
|
|
25
|
+
break
|
|
26
|
+
reply += chunk
|
|
27
|
+
print(reply.decode().strip() or "no reply")
|