@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,101 @@
1
+ ---
2
+ name: hivey-grok
3
+ description: Run tasks with xAI's Grok Build CLI (`grok`, installed at ~/.grok/bin/grok) headless through a bundled uv Python runner — research questions (web search, "what's X/Twitter saying about…", trend scans with source links), quick answers, structured JSON extraction, or coding work in a folder — then check the result and report cost. Also manages grok itself: models, sessions, resuming, login, usage limits, updates, config and docs. Use whenever the user says "grok", "ask Grok", "with Grok", "grok -p", wants a Grok/xAI second opinion, or wants a Grok-powered scan of X/Twitter discussion, even if they don't say "CLI". Not for the grok.com web app in Chrome (use grok-research / deep-research-duo) and not for calling the xAI API from code.
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
+ # grok: run tasks with the Grok Build CLI
11
+
12
+ `grok` is xAI's agentic CLI (like Claude Code): it can search/fetch the web, read and edit files,
13
+ run shell commands and spawn subagents. Headless mode (`-p`) runs one prompt and exits.
14
+
15
+ Runner: `uv run -q --script ~/.claude/skills/hivey-grok/scripts/grok_run.py` (called `RUN` below).
16
+ Stdlib-only; wraps `~/.grok/bin/grok -p … --output-format json`, prints the answer to stdout
17
+ and a one-line `[grok] stop=… turns=… session=… cost=$…` summary to stderr.
18
+
19
+ ## Why the runner and not bare `grok -p`
20
+
21
+ Two things bit us when we ran grok headless directly:
22
+ - **Tool calls that need approval are silently cancelled.** The JSON comes back with
23
+ `stopReason: "cancelled"` and a half-finished answer. The first `web_fetch` is enough to
24
+ trigger it. The runner turns this into exit code 3 and prints a hint.
25
+ - **Unrestricted, grok explores the machine.** For an "search X for…" prompt it read
26
+ `~/.claude/skills/*`, looked for local CLIs, and tried to drive Chrome through agent-browser.
27
+ That burned 17 turns (~$0.54) and hit the free-tier limit. `--research` stops this: it allows
28
+ WebSearch/WebFetch, denies Bash/Edit/Write/MCP, and adds a rule to cite URLs.
29
+ `--tools` would be the obvious fix, but it needs internal tool IDs and ignores names it doesn't know.
30
+
31
+ The runner also runs in a scratch `--cwd` (`/tmp/grok-runs`) by default, so grok doesn't index
32
+ whatever repo you happen to be in.
33
+
34
+ ## 1. Pick the mode
35
+
36
+ | Task | Command |
37
+ |---|---|
38
+ | Research / news / "what's X saying" / trends with links | `RUN --research "<prompt>"` |
39
+ | Quick answer, explanation, rewrite | `RUN "<prompt>"` (add `--max-turns 3` to keep it cheap) |
40
+ | Structured extraction | `RUN --schema '<json schema or file.json>' "<prompt>"` → prints JSON |
41
+ | Code/file work in a project | `RUN --code --cwd <project> "<task>"` (auto-approves edits and shell; only in a folder the user named) |
42
+ | Follow-up in the same conversation | `RUN -c --cwd <same dir> "<follow-up>"` or `RUN -r <session-id> "<follow-up>"` |
43
+ | Long prompt | write it to a file and use `cat prompt.md \| RUN --research -` |
44
+
45
+ Useful extras: `--save out.md` (write the answer to a file), `--json` (full envelope with usage),
46
+ `-m <model>`, `-e low|medium|high|xhigh|max` (reasoning effort), `--max-turns N` (cost cap),
47
+ `--allow '<Rule>'` / `--deny '<Rule>'` (e.g. `--allow 'Bash(git *)'`), `--timeout 900`.
48
+
49
+ Research runs take 1–4 minutes. Run them with a long Bash timeout (600000 ms) or in the background.
50
+
51
+ ## 2. Write the prompt
52
+
53
+ Grok does what the prompt literally says, so be specific about:
54
+ - **Scope and time window**: "last 7 days", "since 2026-10-08". Grok knows today's date.
55
+ - **Sources**: "posts on X (x.com)", "GitHub repos", "Hacker News threads".
56
+ - **Output shape**: sections, a table, or "top 10 with one line each".
57
+ - **Evidence**: "include the original post URL for every item; skip items you can't link".
58
+
59
+ Example (the user's own):
60
+ ```bash
61
+ RUN --research --save ~/Desktop/agent-frameworks.md \
62
+ "Search X for the most discussed AI agent frameworks over the last 7 days. Identify emerging trends, recurring complaints, and promising new projects. Include links to the original posts."
63
+ ```
64
+
65
+ **About X/Twitter data**: on this account the CLI has no native X-search connector. It sees X
66
+ through web search and fetch, and x.com pages often need a login. Expect fewer and less fresh
67
+ X links than grok.com's in-app search gives. If the answer comes back thin on actual post URLs,
68
+ tell the user, and offer the Chrome-based `grok-research` / `deep-research-duo` skills, which use
69
+ grok.com directly.
70
+
71
+ ## 3. Check and report
72
+
73
+ - Exit 0: show the answer, or summarise it if it's long and was saved with `--save`. Include
74
+ the cost/turns line, and mention the session id when a follow-up is likely.
75
+ - Spot-check that links are real `x.com/<user>/status/<id>` (or the asked-for source) URLs, not
76
+ invented or generic search URLs. Mention any that look made up.
77
+ - Exit codes: `1` error (message printed) · `2` **usage limit**: the free Grok Build quota is
78
+ exhausted, so tell the user to wait or upgrade to SuperGrok; don't retry in a loop · `3` cancelled
79
+ by a permission prompt, so rerun with the right mode or `--allow` · `4` empty answer ·
80
+ `124` timeout.
81
+
82
+ ## 4. Managing grok itself
83
+
84
+ These don't need the runner. They're plain `grok` subcommands:
85
+
86
+ | Need | Command |
87
+ |---|---|
88
+ | Version / update | `grok --version` · `grok update` |
89
+ | Auth status / login | `grok models` (first line shows login) · `grok login` (browser) · `grok login --device-auth` · or `XAI_API_KEY` env |
90
+ | Models | `RUN --models` |
91
+ | Sessions | `RUN --sessions` (per cwd) · `grok sessions search <q>` · `grok export <id>` (transcript as Markdown, good for seeing which tools it used) |
92
+ | Token/cost of a session | `grok usage <session-id>` |
93
+ | Config in effect | `grok inspect` · file: `~/.grok/config.toml` |
94
+ | MCP servers / plugins / memory | `grok mcp …` · `grok plugin …` · `grok memory …` |
95
+ | Health check | `grok doctor` · `grok du` (disk use of ~/.grok) |
96
+ | Interactive TUI | `grok` or `grok "<initial prompt>"`. Can't run inside Claude Code's Bash; tell the user to run it with `! grok` or in their own terminal |
97
+
98
+ Full docs ship with the CLI in `~/.grok/docs/user-guide/`. Read only the file you need:
99
+ `14-headless-mode.md` (flags, JSON format, exit codes), `22-permissions-and-safety.md`
100
+ (allow/deny rule syntax), `17-sessions.md`, `07-mcp-servers.md`, `26-config-reference.md`,
101
+ `02-authentication.md`.
@@ -0,0 +1,139 @@
1
+ #!/usr/bin/env -S uv run --script
2
+ # /// script
3
+ # requires-python = ">=3.11"
4
+ # dependencies = []
5
+ # ///
6
+ """Run the Grok Build CLI (`grok`) headless from Python.
7
+
8
+ Examples:
9
+ grok_run.py "What changed in Python 3.14?"
10
+ grok_run.py --research "Search X for the most discussed AI agent frameworks over the last 7 days ..."
11
+ grok_run.py --research --save ~/Desktop/agents.md "..." # also write the answer to a file
12
+ grok_run.py --code --cwd ~/projects/app "Fix the failing test in tests/test_api.py"
13
+ grok_run.py --schema '{"type":"object","properties":{"major":{"type":"integer"}}}' "Parse v2.14.3"
14
+ grok_run.py -c "Now go deeper on the second trend" # continue last session in --cwd
15
+ grok_run.py -r <session-id> "Follow-up question"
16
+ echo "long prompt" | grok_run.py -
17
+ grok_run.py --models | --sessions
18
+ """
19
+ import argparse
20
+ import json
21
+ import os
22
+ import subprocess
23
+ import sys
24
+ from pathlib import Path
25
+
26
+ GROK = os.environ.get("GROK_BIN", str(Path.home() / ".grok/bin/grok"))
27
+ SCRATCH = Path("/tmp/grok-runs")
28
+
29
+ # Research mode: search and fetch the web, nothing else. Without these, headless grok
30
+ # cancels on the first web_fetch approval, or wanders into shell/browser automation.
31
+ RESEARCH_PERMS = ["--allow", "WebSearch", "--allow", "WebFetch",
32
+ "--deny", "Bash", "--deny", "Edit", "--deny", "Write", "--deny", "MCPTool"]
33
+ RESEARCH_RULES = ("Answer using only web_search and web_fetch. Do not run shell commands, "
34
+ "read local files, drive a browser or look for local tools. "
35
+ "Cite every claim with the original URL. If a source can't be reached, "
36
+ "say so and continue with what you have.")
37
+
38
+
39
+ def build_cmd(a, prompt: str) -> list[str]:
40
+ cmd = [GROK, "-p", prompt, "--output-format", "json", "--no-auto-update"]
41
+ if a.model:
42
+ cmd += ["-m", a.model]
43
+ if a.effort:
44
+ cmd += ["--effort", a.effort]
45
+ if a.max_turns:
46
+ cmd += ["--max-turns", str(a.max_turns)]
47
+ if a.schema:
48
+ schema = Path(a.schema).expanduser()
49
+ cmd += ["--json-schema", schema.read_text() if schema.is_file() else a.schema]
50
+ if a.cont:
51
+ cmd += ["-c"]
52
+ if a.resume:
53
+ cmd += ["-r", a.resume]
54
+ if a.research:
55
+ cmd += RESEARCH_PERMS + ["--rules", RESEARCH_RULES]
56
+ if a.code:
57
+ cmd += ["--always-approve"]
58
+ for rule in a.allow:
59
+ cmd += ["--allow", rule]
60
+ for rule in a.deny:
61
+ cmd += ["--deny", rule]
62
+ return cmd
63
+
64
+
65
+ def run(a, prompt: str) -> dict:
66
+ p = subprocess.run(build_cmd(a, prompt), capture_output=True, text=True, cwd=a.cwd,
67
+ env={**os.environ, "GROK_DISABLE_AUTOUPDATER": "1"}, timeout=a.timeout)
68
+ try:
69
+ return json.loads(p.stdout)
70
+ except json.JSONDecodeError:
71
+ return {"type": "error", "message": (p.stderr or p.stdout).strip() or f"exit {p.returncode}"}
72
+
73
+
74
+ def main() -> int:
75
+ ap = argparse.ArgumentParser(description="Run grok (Grok Build CLI) headless")
76
+ ap.add_argument("prompt", nargs="?", help="prompt text, or '-' to read stdin")
77
+ mode = ap.add_mutually_exclusive_group()
78
+ mode.add_argument("--research", action="store_true", help="web search/fetch only, cite URLs")
79
+ mode.add_argument("--code", action="store_true", help="auto-approve all tools in --cwd (edits, shell)")
80
+ ap.add_argument("-m", "--model", help="model id (see --models)")
81
+ ap.add_argument("-e", "--effort", help="none|minimal|low|medium|high|xhigh|max")
82
+ ap.add_argument("--max-turns", type=int, help="cap agent turns (limits cost)")
83
+ ap.add_argument("--schema", help="JSON schema string or path to a .json file")
84
+ ap.add_argument("--cwd", type=lambda s: str(Path(s).expanduser()),
85
+ help="working dir (default: /tmp/grok-runs scratch dir)")
86
+ ap.add_argument("-c", "--continue", dest="cont", action="store_true", help="continue last session in --cwd")
87
+ ap.add_argument("-r", "--resume", help="resume a session id")
88
+ ap.add_argument("--allow", action="append", default=[], help="extra permission allow rule")
89
+ ap.add_argument("--deny", action="append", default=[], help="extra permission deny rule")
90
+ ap.add_argument("--timeout", type=int, default=900, help="seconds before killing grok (default 900)")
91
+ ap.add_argument("--save", help="also write the answer to this file")
92
+ ap.add_argument("--json", action="store_true", help="print the full JSON envelope")
93
+ ap.add_argument("--models", action="store_true", help="list models and exit")
94
+ ap.add_argument("--sessions", action="store_true", help="list recent sessions and exit")
95
+ a = ap.parse_args()
96
+
97
+ if a.models:
98
+ return subprocess.run([GROK, "models"]).returncode
99
+ if a.sessions:
100
+ return subprocess.run([GROK, "sessions", "list"], cwd=a.cwd).returncode
101
+ if not a.prompt:
102
+ ap.error("prompt required (or --models / --sessions)")
103
+ prompt = sys.stdin.read() if a.prompt == "-" else a.prompt
104
+ if not a.cwd:
105
+ SCRATCH.mkdir(parents=True, exist_ok=True)
106
+ a.cwd = str(SCRATCH)
107
+
108
+ try:
109
+ r = run(a, prompt)
110
+ except subprocess.TimeoutExpired:
111
+ print(f"[TIMEOUT] grok ran longer than {a.timeout}s", file=sys.stderr)
112
+ return 124
113
+
114
+ if a.json:
115
+ print(json.dumps(r, indent=2, ensure_ascii=False))
116
+ if r.get("type") == "error":
117
+ if not a.json:
118
+ print(f"[ERROR] {r.get('message')}", file=sys.stderr)
119
+ return 2 if "usage limit" in r.get("message", "") else 1
120
+
121
+ text = r.get("text", "")
122
+ if not a.json:
123
+ print(text)
124
+ if a.save:
125
+ Path(a.save).expanduser().write_text(text)
126
+ cost = r.get("total_cost_usd")
127
+ print(f"[grok] stop={r.get('stopReason')} turns={r.get('num_turns')} session={r.get('sessionId')}"
128
+ + (f" cost=${cost:.3f}" if cost is not None else ""), file=sys.stderr)
129
+ if r.get("stopReason") == "cancelled":
130
+ print("[CANCELLED] a tool call needed approval. Use --research, --code, or --allow <Rule>.",
131
+ file=sys.stderr)
132
+ return 3
133
+ if not text.strip():
134
+ return 4
135
+ return 0
136
+
137
+
138
+ if __name__ == "__main__":
139
+ sys.exit(main())
@@ -0,0 +1,384 @@
1
+ ---
2
+ name: hivey-swarm-creator
3
+ description: Turn a task into a coordinated swarm of coding agents (Claude Code, Codex, Grok, Antigravity/Gemini) in hivey. This session becomes the coordinator (the swarm's master) - it designs the smallest team with the user, always adds a critic, writes a detailed CLAUDE.md brief per agent with deliverables and runnable checks, sets up the task board, git worktrees, the swarm's wiki, skills and Slack, launches it with `hivey swarm launch`, and then coordinates it. Use whenever the user says "swarm", "/swarm", "/hivey-swarm-creator", "spin up a team of agents", "launch multiple agents for this", "split this across agents", "create agents to build/research X in parallel", or otherwise wants several agents working together on one project, even if they don't say the word swarm. Also use to pause, resume, restart or continue an existing swarm ("pause the swarm", "stop the agents and save progress", "resume the swarm").
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 swarm creator
11
+
12
+ You are the **coordinator**. You don't become one of the workers: you design the team with the
13
+ user, set it up, launch it, and then stay on as its master (pane 1 of the swarm's space). The
14
+ user wants a team that runs with little supervision, so most of the value is in the design and
15
+ the per-agent CLAUDE.md briefs.
16
+
17
+ You run either as the setup pane of `hivey swarm new "<task>"` (`HIVEY_SETUP_TASK` holds the
18
+ task, `HIVEY_SETUP_CWD` the folder it was started from) or because the user typed
19
+ `/hivey-swarm-creator` in a hivey pane. The `hivey` skill knows every hivey command;
20
+ `hivey swarm <command> --help` shows usage without running anything.
21
+
22
+ Scripts live in `~/.claude/skills/hivey-swarm-creator/scripts/` (or
23
+ `~/.agents/skills/hivey-swarm-creator/scripts/` for Codex), called `$S` below. Standard library only.
24
+
25
+ **House rules** (`references/shared-rules.md`) apply to you and every agent: end every final
26
+ response with `DONE: <3 words max>` on its own line (hivey's Stop hook speaks it for masters
27
+ and solo agents; workers stay silent), look up docs with `hivey-context7` first, respect the
28
+ safety hooks, keep secrets out of files, style Obsidian notes with callouts.
29
+
30
+ ## Preconditions
31
+
32
+ - `test "$HIVEY_ENV" = 1`: you must be inside hivey. If not, say so and stop.
33
+ - **Folder** = `HIVEY_SETUP_CWD`, else the current directory, unless the user named another.
34
+ The **swarm root** is `<Folder>/<name>` (step 1). Agent homes go in `<root>/<agent>/`; the
35
+ shared work product goes in `<root>/` or a subfolder (e.g. `<root>/app/`). Every agent gets
36
+ access to the whole root.
37
+ - **Resuming?** If `<root>/.swarm/agents.json` already exists (or the current folder is a swarm
38
+ root), this swarm has run before. Follow **Resume a swarm** instead of designing a new one,
39
+ unless the user asks for a new or changed team.
40
+
41
+ ## 1. Name (ask first)
42
+
43
+ Ask the user for the swarm's **name** (suggest one from the task; `[a-z][a-z0-9-]{0,18}`),
44
+ unless the task already says "Name: …". That one name is used everywhere: the slug
45
+ (`--slug`), the Slack channel `#<name>`, the root `<Folder>/<name>` and the wiki
46
+ `<root>/<name>-wiki`. No `swarm-` prefix anywhere. Below, `<name>` and `<slug>` are the same.
47
+ In the same question suggest an **emoji** for it (e.g. 📈 for trading, 📡 for a news radar)
48
+ unless the task already says "Icon: …"; the sidebar shows the space as `<emoji> <name>`
49
+ (`--icon`, step 7). The user can pick another or none.
50
+
51
+ ## 2. Design the team
52
+
53
+ Work out the **smallest team** that covers the task, usually 2–5 workers. Each one costs
54
+ attention and coordination, so give each a **distinct deliverable**. If one agent needs
55
+ another's output, make that hand-off explicit instead of having two agents share a job.
56
+
57
+ **Every swarm includes a `critic`**, on top of the workers. It produces nothing itself: it
58
+ reviews each deliverable posted as DONE, sends concrete critique to the owner, and approves the
59
+ work once it's good, so the team improves its drafts instead of shipping them. Tailor its
60
+ criteria to the project (code: correctness, tests, security; research: sources, gaps, logic;
61
+ copy: clarity, audience fit) and put them in its CLAUDE.md.
62
+
63
+ For each agent decide:
64
+ - **key**: short kebab-case role matching `[a-z][a-z0-9_-]{0,31}` (`researcher`, `builder`,
65
+ `designer`). It's the folder name and the address for `hivey msg send <key>`.
66
+ - **mission and deliverables**: exact output paths and an objective **"done when"** for each.
67
+ - **dependencies**: who it needs input from and who consumes its output.
68
+ - **coding agent** (`--kinds`): which CLI runs it. Claude Code is the default. Suggest per
69
+ role: **Claude Code** for most work and the critic; **Codex** for code review or a second
70
+ opinion; **Grok** for X/Twitter and web research; **agy** (Antigravity, Gemini) for fast,
71
+ cheap tasks and image generation. All four read the CLAUDE.md you write: launch links
72
+ `AGENTS.md` (and `GEMINI.md` for agy) to it.
73
+ - **model** (`--models`): for Claude Code, `opus` for builders, the critic and deep reasoning;
74
+ `sonnet` for research, writing and data gathering, at a fraction of the cost. A swarm costs
75
+ many times what one agent does, so spend the strong model where it pays off. For Codex, Grok
76
+ and agy leave it to the CLI's default unless the user names one.
77
+ - **skills**: run `hivey skills guide` and follow it for every agent (skylls first, skills.sh
78
+ only with the user's OK). Skills go in the plan per agent and land in each agent's own
79
+ `.claude/skills/`, never globally. Capabilities no skill covers are **skill gaps**: list them
80
+ as suggestions (`/skill-creator`), don't build them now.
81
+
82
+ Then break the work into a **task list** for the task board. Each task has an ID, title, owner,
83
+ dependencies, deliverable path and, where possible, a **`check` command**: a shell command that
84
+ exits 0 only when the deliverable is really done (`npm test`, `pytest -q`,
85
+ `test -s report.md && grep -q '## Sources' report.md`, a link checker, a schema validator).
86
+ Runnable checks catch "claimed done but isn't", which prose criteria miss. Most failed
87
+ multi-agent runs come from vague specs, agents out of sync or missing verification; the board,
88
+ contracts and checks target exactly those.
89
+
90
+ **Contracts first** when agents build things that must fit together (code, data, APIs, file
91
+ formats): task T1 is "Write `<root>/shared/CONTRACTS.md`" (interfaces, data shapes, formats,
92
+ naming, layout), with a check, and every build task depends on it, so no builder starts before
93
+ the critic approves the contract.
94
+
95
+ **Code swarms: one git worktree per builder.** When two or more agents write code in the same
96
+ repo, each gets its own worktree and branch (step 6) so they never overwrite each other. Name an
97
+ **integrator** (the critic, or a dedicated agent for bigger builds) who merges the branches into
98
+ the main checkout and runs the full test suite on the combined result, as its own task with a
99
+ check.
100
+
101
+ **Mobile apps (iPhone, iOS, Android): build them with Expo**: Expo SDK (latest stable) + Expo
102
+ Router + TypeScript. Don't plan native Swift/Kotlin projects, even if a spec says "native". The
103
+ app runs through Expo tooling (`npx expo start`, `npx expo run:ios`, a dev-client build via
104
+ `expo prebuild`). Shared logic goes in plain TS packages; anything that must be native
105
+ (widgets, Live Activities, extensions) goes in as Expo modules or targets through config
106
+ plugins, not a hand-maintained Xcode project. Give the mobile builder Expo skills (the
107
+ `expo:*` plugin skills if installed, or via `hivey skills guide`) and make its check an Expo
108
+ command (`npx tsc --noEmit`, the tests, a prebuild + simulator build). Anything that needs the
109
+ user's EAS or App Store account stays with the user.
110
+
111
+ **Budget**: agree a time budget with the user (e.g. 120 min). The watcher warns you at 80% and
112
+ 100%.
113
+
114
+ ## 3. Confirm with the user
115
+
116
+ Show the plan and wait for approval before creating anything:
117
+
118
+ ```
119
+ Swarm: <emoji> <name> root: <Folder>/<name> channel: #<name> budget: <N> min
120
+ | Agent | CLI | Model | Role / mission | Deliverables (path) | Skills | Depends on |
121
+ Tasks:
122
+ | ID | Task | Owner | Deps | Check |
123
+ Skill gaps: <gap> → suggestion …
124
+ Code: <repo path>, worktrees for <builders>, integrator: <agent> (code swarms only)
125
+ (critic always included)
126
+ Wiki: <root>/<name>-wiki (the swarm's memory; say no to skip it)
127
+ Slack: #<name> (connected) | not connected: run `hivey slack connect` first, or go without
128
+ Schedules: monitoring pass every <N> min · <timed task> … (or none)
129
+ Addons: hivey.dashboard, hivey.slack-relay, hivey.swarm-watcher
130
+ Publish: product repo <name>, swarm repo <name>-swarm, private (only if it builds something)
131
+ ```
132
+
133
+ In the same message:
134
+ - **Confirm each agent's CLI and model.** Show them per agent with a one-line reason
135
+ ("builder: Claude Code opus, writes the core code"; "researcher: Grok, X and web research";
136
+ "reviewer: Codex, second opinion on the code") and ask whether to keep or change them. The
137
+ user pays for every agent, so this is their call, not a default to apply silently.
138
+ - **Ask whether you should run scheduled checks**, and how:
139
+ - a **monitoring pass** every N minutes (who is idle, blocked or stuck; answer questions;
140
+ review finished work). Suggest 15 min, shorter for fast swarms, longer for long research.
141
+ - **timed tasks** with their own instructions ("every day at 09:00 summarize progress to the
142
+ user", "every 2 h run the test suite and file failures").
143
+ - or **none** (you only react to messages and alerts).
144
+ Each wake-up costs a turn of your model.
145
+ - **Slack**: run `hivey slack status` before showing the plan. Connected: `hivey swarm launch`
146
+ creates (or joins) `#<name>`, invites the user and starts the relay, nothing else to do. Not
147
+ connected: ask the user to run `hivey slack connect` in a terminal (never ask for the token in
148
+ chat), or go on without Slack if they prefer.
149
+ - **GitHub**: if the swarm builds something, ask whether to publish (product and swarm are
150
+ separate repos; see step 7).
151
+
152
+ The wiki always lives **inside the swarm folder**, at `<root>/<name>-wiki`, so the swarm, its
153
+ agents and its knowledge can be moved or shared as one folder. Never ask where the user's
154
+ Obsidian is. In anything an agent reads, write it relative to the agent's folder:
155
+ `../<name>-wiki`. Adjust the plan until the user says yes.
156
+
157
+ ## 4. Scaffold the swarm
158
+
159
+ ```bash
160
+ mkdir -p <root>/shared
161
+ python3 $S/shared_rules.py <root> # house rules into <root>/CLAUDE.md (marked block)
162
+ python3 $S/setup_agent.py <root> <agent> [--worktree <root>/app] # once per agent, critic too
163
+ ```
164
+
165
+ `setup_agent.py` creates `<root>/<agent>/` and its `.claude/settings.json`, which grants access
166
+ to the swarm root (`permissions.additionalDirectories`, plus `--vault` if the vault lives
167
+ elsewhere) and sets `AGENTS_TTS=0` so workers stay silent. **Code swarms:** make sure the repo
168
+ (e.g. `<root>/app`) exists with at least one commit, then pass `--worktree <repo>` for each
169
+ builder: it gets `<root>/<agent>/repo` on branch `swarm/<agent>`. Builders commit on their
170
+ branch; the integrator merges into the main checkout and runs the checks there.
171
+
172
+ Then install each agent's skills as `hivey skills guide` says (step 4 of the guide), and check
173
+ `ls <root>/<agent>/.claude/skills`.
174
+
175
+ **Task board.** Load the approved task list. Always pass `--root <root>`, since your working
176
+ directory may not be under the root:
177
+
178
+ ```bash
179
+ T="python3 $S/swarm_tasks.py --root <root>"
180
+ $T add T1 "Write shared/CONTRACTS.md" --owner builder --path shared/CONTRACTS.md \
181
+ --check "test -s shared/CONTRACTS.md"
182
+ $T add T2 "Build the API" --owner builder --deps T1 --path app/ --check "cd app && npm test"
183
+ ```
184
+
185
+ This writes `.swarm/tasks.json` (the `hivey.dashboard` reads it), a readable `.swarm/TASKS.md`,
186
+ and `.swarm/events.jsonl`, the swarm's timeline. Rules the board enforces: agents **claim**
187
+ before starting, only their own (or unowned) tasks, and only once every dependency is
188
+ `approved`. Only `critic` or `coordinator` can set `approved`, and only when the task's check
189
+ passes (checks run outside the board lock, so a slow suite doesn't block anyone). Statuses:
190
+ `open → in-progress → review → approved` (`blocked` any time).
191
+
192
+ ## 5. Write the briefs
193
+
194
+ Read `references/agent-claude-md.md` now: it has the template and role guidance. The briefs are
195
+ the heart of the swarm. Each agent works only from its own file, so it must understand the
196
+ whole team, not just its own job.
197
+
198
+ 1. **Write "The swarm" section once**: setup (root, the swarm's space, you as master, Slack
199
+ mirror, wiki), the **full roster** (every agent including you and the critic: key, CLI, role,
200
+ what it owns, what to ask it for), a "who to talk to" list, the task board, the hand-off
201
+ chain, critique loop, messaging, contracts and code, safety, secrets and docs. Save it as
202
+ `<root>/.swarm/README.md`.
203
+ 2. **Write `<root>/<agent>/CLAUDE.md` for each agent**: its own sections (mission, scope,
204
+ deliverables with paths and checks, skills, method, definition of done, Status) plus that
205
+ swarm section pasted in **verbatim**, so every agent sees the same roster and rules.
206
+
207
+ Make each brief detailed and specific: quote the user's original request, use exact paths, and
208
+ name the real agents in the commands. A vague brief leads to an agent that idles, duplicates a
209
+ teammate or asks the wrong agent.
210
+
211
+ ## 6. Create the wiki (memory)
212
+
213
+ Unless the user said no, create the swarm's Obsidian wiki with the **`hivey-create-wiki`**
214
+ skill (Skill tool, args `<name> --in <root> --agent <root>/<agent> [--agent …]`, every agent
215
+ including the critic) now that the briefs exist. It reads the briefs, tailors the vault and
216
+ patches every agent's CLAUDE.md. Answer any question it has from the plan instead of asking the
217
+ user again. If the vault already exists (a resumed swarm), reuse it. Shape it for a swarm:
218
+ - `raw/reports/<agent>/` for each worker and the critic: agents write their reports there, and
219
+ only there.
220
+ - `wiki/` sub-folders: `agents/`, `findings/`, `decisions/`, `deliverables/`, `lessons/`.
221
+ - In the vault's CLAUDE.md add the swarm rule: *only the coordinator writes `wiki/`; it ingests
222
+ agent reports from `raw/reports/` without waiting to discuss them, because the swarm runs
223
+ unattended.* Agents writing `index.md`/`log.md` in parallel would clobber each other.
224
+
225
+ Then initialize the memory: `wiki/swarm-overview.md` (the user's request, goal, roster, Slack
226
+ channel, root, hand-off chain), `wiki/agents/<agent>.md` per agent (role, owns, deliverables,
227
+ report folder, status "not started"), `wiki/decisions/plan.md` (the approved plan and the
228
+ user's tweaks), linked from `index.md`, with a `bootstrap` entry in `log.md`.
229
+
230
+ ## 7. Launch
231
+
232
+ ```bash
233
+ hivey swarm launch <root> --slug <name> --icon <emoji> <agent>... critic \
234
+ --models builder=opus,critic=opus,writer=sonnet --kinds reviewer=codex,scout=grok \
235
+ --budget-min 120 --heartbeat 15m \
236
+ --heartbeat-task "Monitoring pass: follow the hivey-swarm-creator skill's monitoring pass" \
237
+ --addon hivey.dashboard --addon hivey.swarm-watcher \
238
+ --kickoff "Read your CLAUDE.md, then send START to coordinator as it says."
239
+ ```
240
+
241
+ - This pane becomes the master `<name>-coordinator` and moves into a new space `<name>`; the
242
+ agents open beside it, each as `<name>-<agent>` in its own folder, run unattended.
243
+ - Slack: when connected, launch creates (or joins) `#<name>`, invites the user and starts
244
+ `hivey.slack-relay`. Post a short kickoff there (goal, roster); `hivey swarm info <name>`
245
+ shows the channel.
246
+ - Addons: `hivey.dashboard` (states, tokens per agent, active time vs budget, tasks, messages),
247
+ `hivey.slack-relay` (Slack ⇄ bus) and `hivey.swarm-watcher` (stalled, blocked, idle and budget
248
+ alerts to you, plus a live Gantt dashboard in Chrome; see `references/dashboard.md`). Missing
249
+ addons are reported and skipped; check `hivey plugin list`. Reopen one later with
250
+ `hivey swarm addon <name> <id>`.
251
+ - Leave out `--heartbeat` if the user chose no monitoring pass. Add timed tasks with
252
+ `hivey swarm schedule add <name> --at 09:00 [--id ID] "<instructions>"` or `--every 2h`
253
+ (`--to <agent>` wakes an agent instead of you); `hivey swarm schedule list|remove|run <name>
254
+ [<id>]`. Each wake-up arrives as a `[hivey]` message with the task and a status snapshot, only
255
+ when you're idle; one still waiting is never duplicated, and paused swarms are skipped.
256
+ - **Directory**: register what the swarm does so other swarms and agents can judge whether to ask
257
+ it for help: `hivey swarm profile <name> --description "<one line>" --skills a,b --tools "gh, …"`.
258
+ Only you (the master) may message another swarm (`hivey msg send <slug>/master "…"`), and only
259
+ after the user says yes; don't disturb one marked busy.
260
+ - **GitHub**: if the user wants the product published, keep it in its own folder (default
261
+ `<root>/app`, or `"product_dir"` in `.swarm/agents.json`) with its own git repo, and run
262
+ `hivey swarm addon <name> hivey.github`: it shows the plan, the user confirms in that pane,
263
+ and secrets are scanned before each first push. Never create or push repos without that.
264
+
265
+ Tell the user what's running: the space, agents, CLIs, Slack channel, wiki path, dashboards,
266
+ schedules and skill gaps.
267
+
268
+ ### Save and share (skylls)
269
+
270
+ If `skylls --version` works, offer to save the swarm once it's running, so the user can reuse
271
+ and share it. Only with their yes: `skylls swarms push <root> -m "<what it does>"`, plus
272
+ `skylls push <skill folder>` for any new skill you wrote. Push scans for secrets and personal
273
+ data and refuses if it finds any: remove them, never pass `--skip-scan`. Share
274
+ (`skylls swarms share <name> @user`) only when the user asks. Before designing a new swarm,
275
+ `skylls --json swarms find <words> --limit 5` may show one that already fits.
276
+
277
+ ## 8. Coordinate
278
+
279
+ **The wiki is your source of truth too.** Read `wiki/index.md`, `swarm-overview.md`, the agent
280
+ pages and recent `findings/`/`decisions/` whenever you start or resume coordinating, and before
281
+ any decision that depends on what the swarm knows. If an agent's claim or your memory conflicts
282
+ with the wiki, check the source, then correct the wiki or the agent, so there is one truth.
283
+
284
+ Watch the agents, not just their messages:
285
+
286
+ ```bash
287
+ hivey swarm list # states (working/idle/blocked) + queued messages
288
+ hivey agent read <name>-<agent> --source recent-unwrapped --lines 120 # what it is doing/said
289
+ hivey msg inbox # messages for you
290
+ hivey msg log --swarm <name> --limit 40 # the team's traffic
291
+ hivey swarm info <name> # channel, vault, addons, budget, tasks
292
+ ```
293
+
294
+ You reach agents with `hivey msg send <agent> "…"` (`@all`, `@role:worker`, `--fyi` never wakes,
295
+ `--urgent` interrupts). Delivery waits until the recipient is idle, and you're told when one is
296
+ blocked. Messages and alerts arrive in your pane as `[hivey]` prompts; handle them as
297
+ coordinator work.
298
+
299
+ **Handling an alert or message** (one agent):
300
+ - **It asked a question**: answer it if it's within the plan; if it's the user's call, ask the
301
+ user and relay the answer.
302
+ - **It says it's done**: check the deliverable exists, meets its "done when" and its check
303
+ passes, that it sent DONE to the critic and wrote its report to the wiki. If anything is
304
+ missing, tell it exactly what.
305
+ - **It's waiting on a teammate**: check that teammate's state and nudge whichever side holds
306
+ things up.
307
+ - **It stopped mid-task** with no question and no DONE: tell it to continue from its own Next
308
+ steps.
309
+ - **Blocked on a dialog**: read its pane first; answer only dialogs you understand, ask the user
310
+ about anything else.
311
+ - **A safety block** (`hivey safety` hooks): decide whether the operation is really needed. If it
312
+ is, ask the user. Never tell an agent to work around a block, and never turn safety off.
313
+ - **Gone** (pane closed or agent exited): `hivey swarm relaunch <name> <agent>`; it continues its
314
+ conversation and its Status section.
315
+
316
+ **Check every START message.** Each agent's first message restates its task and lists its
317
+ assumptions. Compare them with the plan as they arrive: a wrong assumption corrected in minute
318
+ two saves an hour.
319
+
320
+ **A monitoring pass** (each heartbeat, and whenever the user asks for status):
321
+ 1. `hivey swarm list`, then `hivey agent read` for any agent whose state changed since the last
322
+ pass (all of them every third pass). Read `hivey msg log`, `.swarm/TASKS.md` and the tail of
323
+ `.swarm/events.jsonl`.
324
+ 2. Glance at token use on the dashboard. An agent burning tokens while its tasks don't move is
325
+ probably looping: read its pane and redirect it. Compare each agent's work with its tasks;
326
+ flag anything missing, out of scope or duplicated, unclaimed tasks whose deps are approved
327
+ (assign them), and `review` tasks nobody is reviewing.
328
+ 3. Answer open questions, nudge idle agents that still have work, resolve stalled critique.
329
+ 4. Ingest new reports into the wiki (`references/wiki-memory.md`), and update **Swarm status**
330
+ at the bottom of `.swarm/README.md` and in `wiki/swarm-overview.md` (date, each agent's state
331
+ and deliverables, critique rounds, open decisions, what to do first on resume).
332
+ 5. Tell the user only what changed or needs their decision; otherwise keep the pass quiet.
333
+
334
+ **Critique loop.** Every deliverable goes owner → DONE → critic → CRITIQUE r<N> → REVISED →
335
+ APPROVED. If owner and critic disagree, or a deliverable reaches round 3 without APPROVED, you
336
+ decide: accept, re-scope, or give a specific fix, and tell both.
337
+
338
+ **Roster changes** (agents added or re-scoped): update `.swarm/README.md` and the swarm section
339
+ in every agent's CLAUDE.md, then `hivey msg send @all` what changed. A new agent: scaffold it,
340
+ write its brief, and add it with `hivey swarm relaunch <name> <agent>` once it's in the manifest
341
+ (or ask the user to relaunch the swarm).
342
+
343
+ Every agent keeps its own Status section; if one looks stale against its pane output, tell the
344
+ agent to update it. Don't close the swarm's space or panes unless the user asks.
345
+
346
+ **Finishing.** A worker only counts as finished once every deliverable is APPROVED and its final
347
+ report is ingested into the wiki. When all workers and the critic have finished, run the
348
+ connection pass and write `wiki/swarm-final-report.md` (`references/wiki-memory.md`), check the
349
+ deliverables against the user's original request, and give the user the **final report**:
350
+ outcome, where each deliverable is, open risks, next steps and the wiki path. If the `archify`
351
+ skill is installed, add the visual report (`references/archify-report.md`). Then write the
352
+ retrospective (`references/retrospective.md`).
353
+
354
+ ## Pause a swarm
355
+
356
+ When the user says "pause/stop the swarm (for now)" or "save progress for next run":
357
+ 1. Tell every agent: `hivey msg send @all --urgent "Pause: stop at a safe point, save your
358
+ in-progress work to files, and rewrite the Status section of your CLAUDE.md (keep the STATUS
359
+ markers). Then reply PAUSED --fyi and wait."`
360
+ 2. Wait until every agent is idle in `hivey swarm list` and its CLAUDE.md changed after the
361
+ pause began (`ls -l <root>/*/CLAUDE.md`). For any that didn't save, read its pane and ask
362
+ again, or write what you can see into `.swarm/README.md`. Never invent its status.
363
+ 3. `hivey swarm pause <name>`: holds message delivery; schedules skip a paused swarm.
364
+ 4. Record half-done work in **Swarm status** (`.swarm/README.md` and `wiki/swarm-overview.md`):
365
+ what's approved, what's open, who does what first on resume, and the resume command. Log it:
366
+ `python3 $S/swarm_tasks.py --root <root> log pause --as coordinator --note "<reason>"`.
367
+ 5. Tell the user it's paused, what's saved where, and how to resume. Panes and sessions stay;
368
+ stopping the hivey session would stop the agents, so only do that if the user asks.
369
+
370
+ ## Resume a swarm
371
+
372
+ When `<root>/.swarm/agents.json` exists, the team, briefs, skills and channel already exist, and
373
+ each agent's memory is its Status section.
374
+ 1. Read the wiki first (`index.md`, `swarm-overview.md`, `swarm-final-report.md` if present,
375
+ agent pages, recent findings and decisions), then `.swarm/README.md` (Swarm status),
376
+ `.swarm/TASKS.md` and each agent's Status. Summarize for the user where each agent left off
377
+ and what's next, and ask how much time remains.
378
+ 2. `hivey swarm resume <name>` releases message delivery. If agents exited or their panes are
379
+ gone (e.g. after a restart), `hivey swarm relaunch <name> [<agent>...]` starts them again,
380
+ continuing their conversations, and reopens dead addons (`--addons-only` for just those).
381
+ 3. `hivey msg send @all "Resumed: read the wiki and your Status, then continue from Next steps
382
+ and send RESUMED to coordinator."` Check each RESUMED reply against the Swarm status notes.
383
+ 4. Coordinate as in step 8. For roster changes, update every brief first. Use
384
+ `hivey swarm launch` again only for a brand-new team or when the manifest is missing.