@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.
Files changed (83) hide show
  1. package/README.md +235 -2
  2. package/bin/hivey.js +98 -0
  3. package/native/darwin-arm64/hivey +0 -0
  4. package/package.json +36 -4
  5. package/platforms.json +3 -0
  6. package/repo/LICENSE +201 -0
  7. package/repo/NOTICE +18 -0
  8. package/repo/README.md +148 -0
  9. package/repo/install.sh +365 -0
  10. package/repo/pets/README.md +25 -0
  11. package/repo/pets/hivey-dot/CLAUDE.md +55 -0
  12. package/repo/pets/hivey-dot/build.sh +34 -0
  13. package/repo/pets/hivey-dot/main.swift +750 -0
  14. package/repo/pets/hivey-h/CLAUDE.md +75 -0
  15. package/repo/pets/hivey-h/build.sh +34 -0
  16. package/repo/pets/hivey-h/main.swift +739 -0
  17. package/repo/pets/hivey-prompt/CLAUDE.md +59 -0
  18. package/repo/pets/hivey-prompt/build.sh +34 -0
  19. package/repo/pets/hivey-prompt/main.swift +691 -0
  20. package/repo/pets/pet.py +288 -0
  21. package/repo/pets/shared/HiveyWatch.swift +437 -0
  22. package/repo/pets/test_pet.py +122 -0
  23. package/repo/plugins/README.md +108 -0
  24. package/repo/plugins/agent-creator/herdr-plugin.toml +17 -0
  25. package/repo/plugins/dashboard/dashboard.py +507 -0
  26. package/repo/plugins/dashboard/herdr-plugin.toml +14 -0
  27. package/repo/plugins/dashboard/test_dashboard.py +134 -0
  28. package/repo/plugins/github/github.py +261 -0
  29. package/repo/plugins/github/herdr-plugin.toml +14 -0
  30. package/repo/plugins/github/test_github.py +49 -0
  31. package/repo/plugins/skills/herdr-plugin.toml +11 -0
  32. package/repo/plugins/skills/skills.md +41 -0
  33. package/repo/plugins/slack-relay/connect.py +198 -0
  34. package/repo/plugins/slack-relay/create_channel.py +134 -0
  35. package/repo/plugins/slack-relay/herdr-plugin.toml +15 -0
  36. package/repo/plugins/slack-relay/relay.py +401 -0
  37. package/repo/plugins/slack-relay/slack-app-manifest.json +30 -0
  38. package/repo/plugins/slack-relay/test_connect.py +66 -0
  39. package/repo/plugins/slack-relay/test_create_channel.py +61 -0
  40. package/repo/plugins/slack-relay/test_relay.py +254 -0
  41. package/repo/plugins/swarm-creator/herdr-plugin.toml +17 -0
  42. package/repo/plugins/swarm-watcher/dashboard.py +333 -0
  43. package/repo/plugins/swarm-watcher/herdr-plugin.toml +16 -0
  44. package/repo/plugins/swarm-watcher/usage.py +129 -0
  45. package/repo/plugins/swarm-watcher/watcher.py +191 -0
  46. package/repo/plugins/team-template/herdr-plugin.toml +15 -0
  47. package/repo/plugins/team-template/setup.py +211 -0
  48. package/repo/plugins/team-template/test_setup.py +73 -0
  49. package/repo/plugins/tts/herdr-plugin.toml +15 -0
  50. package/repo/skills/herdr/SKILL.md +214 -0
  51. package/repo/skills/hivey/SKILL.md +322 -0
  52. package/repo/skills/hivey/scripts/handoff.py +27 -0
  53. package/repo/skills/hivey/scripts/new_wiki.py +143 -0
  54. package/repo/skills/hivey-agent-creator/SKILL.md +303 -0
  55. package/repo/skills/hivey-agent-creator/references/agent-claude-md.md +256 -0
  56. package/repo/skills/hivey-agent-creator/references/global-guidelines.md +67 -0
  57. package/repo/skills/hivey-agent-creator/references/reviewer-agent.md +35 -0
  58. package/repo/skills/hivey-agent-creator/scripts/agent_context.py +76 -0
  59. package/repo/skills/hivey-agent-creator/scripts/agent_gate.py +78 -0
  60. package/repo/skills/hivey-agent-creator/scripts/setup_agent.py +288 -0
  61. package/repo/skills/hivey-agy/SKILL.md +123 -0
  62. package/repo/skills/hivey-agy/references/gemini-prompting.md +134 -0
  63. package/repo/skills/hivey-agy/scripts/agy_run.py +146 -0
  64. package/repo/skills/hivey-codex/SKILL.md +66 -0
  65. package/repo/skills/hivey-context7/SKILL.md +56 -0
  66. package/repo/skills/hivey-create-wiki/SKILL.md +329 -0
  67. package/repo/skills/hivey-grok/SKILL.md +101 -0
  68. package/repo/skills/hivey-grok/scripts/grok_run.py +139 -0
  69. package/repo/skills/hivey-swarm-creator/SKILL.md +384 -0
  70. package/repo/skills/hivey-swarm-creator/references/agent-claude-md.md +313 -0
  71. package/repo/skills/hivey-swarm-creator/references/archify-report.md +24 -0
  72. package/repo/skills/hivey-swarm-creator/references/dashboard.md +46 -0
  73. package/repo/skills/hivey-swarm-creator/references/retrospective.md +23 -0
  74. package/repo/skills/hivey-swarm-creator/references/shared-rules.md +39 -0
  75. package/repo/skills/hivey-swarm-creator/references/wiki-memory.md +30 -0
  76. package/repo/skills/hivey-swarm-creator/scripts/setup_agent.py +76 -0
  77. package/repo/skills/hivey-swarm-creator/scripts/shared_rules.py +50 -0
  78. package/repo/skills/hivey-swarm-creator/scripts/swarm_tasks.py +171 -0
  79. package/repo/skills/hivey-wiki-ingest/SKILL.md +45 -0
  80. package/repo/skills/hivey-wiki-lint/SKILL.md +38 -0
  81. package/repo/skills/hivey-wiki-list/SKILL.md +46 -0
  82. package/repo/skills/hivey-wiki-log/SKILL.md +45 -0
  83. 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")