@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,143 @@
1
+ #!/usr/bin/env python3
2
+ """Create an Obsidian wiki vault as the memory of a hivey agent or swarm (LLM-wiki pattern).
3
+
4
+ usage: new_wiki.py <name> [--root FOLDER] [--look-from VAULT] [--agent FOLDER]... [--about TEXT]
5
+
6
+ The vault lives inside the swarm's or agent's own folder, so everything travels together:
7
+ creates <FOLDER>/<name>-wiki/ (raw/ for sources, wiki/ for maintained pages, index.md, log.md,
8
+ CLAUDE.md with the rules, .obsidian/ so Obsidian opens it as a vault) and adds a "Memory"
9
+ section to each --agent FOLDER's CLAUDE.md pointing at it with a relative path. Obsidian lists
10
+ a vault by its folder name, hence <name>-wiki. FOLDER is the swarm root or the solo agent's
11
+ folder (default: the current folder). An existing vault is reused, never overwritten; so is
12
+ an older <FOLDER>/obsidian/ vault.
13
+ Obsidian keeps the look per vault, so a new vault copies the theme, CSS snippets and Style
14
+ Settings of the vault remembered as --look-from (kept in ~/.hivey/wiki.json); without one it
15
+ opens in stock Obsidian.
16
+ Prints JSON: {"ok": true, "path": "...", "existing": false, "look": true, "agents": [...]}.
17
+ """
18
+ import argparse
19
+ import json
20
+ import os
21
+ import re
22
+ import shutil
23
+ import sys
24
+ import time
25
+ from pathlib import Path
26
+
27
+ SETTINGS = Path.home() / ".hivey" / "wiki.json"
28
+ MARKER = "<!-- hivey: wiki memory -->"
29
+ LEGACY_VAULT = "obsidian" # older vaults; Obsidian listed them all as "obsidian"
30
+
31
+ RULES = """# {name} wiki: rules for the agents that keep it
32
+
33
+ This vault is the long-term memory of **{name}**{about}. Agents read it before working and
34
+ write what they learn, so knowledge survives restarts and new sessions.
35
+
36
+ ## Layout
37
+ - `raw/`: sources as they came in (articles, notes, transcripts, exports). Never edited.
38
+ - `wiki/`: maintained pages, one topic per page, linked with [[wikilinks]].
39
+ - `index.md`: every wiki page with a one-line summary. Keep it current.
40
+ - `log.md`: newest first, one line per change: `YYYY-MM-DD what changed (pages)`.
41
+
42
+ ## Working with it
43
+ 1. Before a task: read `index.md`, then the pages that matter.
44
+ 2. New source: save it under `raw/`, then update or create the `wiki/` pages it informs.
45
+ 3. New finding or decision: add it to the right page (create one if none fits), add the page
46
+ to `index.md`, and a line to `log.md`.
47
+ 4. Prefer updating a page over creating a near-duplicate. Cite the `raw/` file a fact came from.
48
+ """
49
+
50
+ MEMORY = """
51
+ {marker}
52
+ ## Memory (Obsidian wiki)
53
+
54
+ Your long-term memory is the Obsidian vault `{path}` (relative to this file's folder). Read
55
+ its `CLAUDE.md` (the rules) and `index.md` before working; save sources in `raw/`, keep
56
+ `wiki/` pages, `index.md` and `log.md` up to date as you learn. Don't keep knowledge only in
57
+ this conversation.
58
+ """
59
+
60
+
61
+ def setting(key, given):
62
+ """The given path (then remembered in ~/.hivey/wiki.json), else the remembered one."""
63
+ try:
64
+ saved = json.loads(SETTINGS.read_text())
65
+ except (OSError, ValueError):
66
+ saved = {}
67
+ if given:
68
+ saved[key] = str(Path(given).expanduser())
69
+ SETTINGS.parent.mkdir(parents=True, exist_ok=True)
70
+ SETTINGS.write_text(json.dumps(saved) + "\n")
71
+ value = saved.get(key)
72
+ return Path(value).expanduser() if value else None
73
+
74
+
75
+ def copy_look(source, dest):
76
+ """Copies the source vault's theme, snippets and Style Settings into dest/.obsidian."""
77
+ src, dst = source / ".obsidian", dest / ".obsidian"
78
+ if not (src / "appearance.json").is_file():
79
+ return False
80
+ shutil.copy2(src / "appearance.json", dst / "appearance.json")
81
+ for folder in ("themes", "snippets"):
82
+ if (src / folder).is_dir():
83
+ shutil.copytree(src / folder, dst / folder)
84
+ style = src / "plugins" / "obsidian-style-settings"
85
+ if style.is_dir():
86
+ shutil.copytree(style, dst / "plugins" / style.name)
87
+ (dst / "community-plugins.json").write_text(json.dumps([style.name]) + "\n")
88
+ return True
89
+
90
+
91
+ def create(path, name, about):
92
+ (path / ".obsidian").mkdir(parents=True)
93
+ (path / "raw").mkdir()
94
+ (path / "wiki").mkdir()
95
+ (path / "CLAUDE.md").write_text(RULES.format(name=name, about=f" ({about})" if about else ""))
96
+ (path / "index.md").write_text(f"# {name} wiki: index\n\n(no pages yet)\n")
97
+ (path / "log.md").write_text(f"# {name} wiki: log\n\n{time.strftime('%Y-%m-%d')} vault created\n")
98
+
99
+
100
+ def vault_name(name):
101
+ """The vault folder, <name>-wiki as a slug (Obsidian lists vaults by folder name)."""
102
+ slug = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-") or "agent"
103
+ return slug if slug.endswith("-wiki") else f"{slug}-wiki"
104
+
105
+
106
+ def link(agent_dir, path):
107
+ """Adds the Memory section to the agent's CLAUDE.md once."""
108
+ brief = Path(agent_dir).expanduser() / "CLAUDE.md"
109
+ text = brief.read_text() if brief.exists() else ""
110
+ if MARKER in text:
111
+ return False
112
+ brief.parent.mkdir(parents=True, exist_ok=True)
113
+ relative = os.path.relpath(path, brief.parent.resolve())
114
+ brief.write_text(text.rstrip("\n") + "\n" + MEMORY.format(marker=MARKER, path=relative))
115
+ return True
116
+
117
+
118
+ def main():
119
+ parser = argparse.ArgumentParser(description="Obsidian wiki memory for a hivey agent or swarm")
120
+ parser.add_argument("name")
121
+ parser.add_argument("--root", default=".", help="swarm or agent folder; the vault is <root>/<name>-wiki")
122
+ parser.add_argument("--look-from", help="vault whose theme new vaults copy; remembered")
123
+ parser.add_argument("--agent", action="append", default=[], help="agent folder to link")
124
+ parser.add_argument("--about", default="", help="one line: what the agent or swarm does")
125
+ args = parser.parse_args()
126
+ look_from = setting("look_from", args.look_from)
127
+ root = Path(args.root).expanduser().resolve()
128
+ path = root / vault_name(args.name)
129
+ legacy = root / LEGACY_VAULT
130
+ if not path.exists() and not legacy.is_symlink() and (legacy / "CLAUDE.md").is_file():
131
+ path = legacy # an older vault: reused as is; `hivey migrate` renames it
132
+ existing = path.exists()
133
+ look = False
134
+ if not existing:
135
+ create(path, args.name, args.about)
136
+ look = bool(look_from) and copy_look(look_from, path)
137
+ linked = [str(Path(a).expanduser()) for a in args.agent if link(a, path)]
138
+ print(json.dumps({"ok": True, "path": str(path), "existing": existing, "look": look, "agents": linked}))
139
+ return 0
140
+
141
+
142
+ if __name__ == "__main__":
143
+ sys.exit(main())
@@ -0,0 +1,303 @@
1
+ ---
2
+ name: hivey-agent-creator
3
+ description: Design, scaffold and launch ONE specialized, long-lived hivey agent (a solo agent, its own master) for a particular task, on Claude Code, Codex, Grok or Antigravity (agy). It gets its own folder, a detailed CLAUDE.md brief (mission, deliverables with runnable checks, method, rules, resumable dated Status), hand-picked skills, project-scoped MCP servers only when needed, tool permissions, an optional done gate, optional Obsidian wiki memory, its Slack channel #<name> and an optional schedule, then it is launched with `hivey swarm launch --solo`. Use whenever the user says "create an agent", "new agent", "make an agent that does X", "an agent that does X every day", "build me an agent for <task>", "/agent-creator", "/hivey-agent-creator", or when it runs as the setup pane of `hivey swarm new --agent`. For a team of cooperating agents use `hivey swarm new` instead.
4
+ argument-hint: <task description or name>
5
+ ---
6
+
7
+ > Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
8
+ > It holds this machine's own additions; hivey updates never touch it, so put local changes
9
+ > there, never here.
10
+
11
+ # hivey agent creator
12
+
13
+ You design, scaffold and launch **one** specialized agent in hivey. You don't become that
14
+ agent: you are the designer. The user wants something that runs with little supervision, so
15
+ most of the value is in the design and in the agent's `CLAUDE.md`, the only brief it will ever
16
+ get.
17
+
18
+ You run either as the setup pane of `hivey swarm new --agent "<task>"` (then `HIVEY_SETUP_TASK`
19
+ holds the task and `HIVEY_SETUP_CWD` the folder the user ran it from) or because the user typed
20
+ `/hivey-agent-creator`. The `/hivey` skill knows every hivey command; `hivey swarm <command>
21
+ --help` shows usage without running anything.
22
+
23
+ Scripts live in `~/.claude/skills/hivey-agent-creator/scripts/` (`$A` below). References are in
24
+ `~/.claude/skills/hivey-agent-creator/references/`.
25
+
26
+ ## 1. Name and folder
27
+
28
+ **Ask for the name first** (one question). Suggest one from the task or the folder's name,
29
+ normalized to `[a-z][a-z0-9-]{0,31}`; skip the question if the task already says "Name: …".
30
+ That one name is used everywhere: the slug (`--slug`), the Slack channel `#<name>` and the
31
+ wiki `<agent folder>/<name>-wiki`. Never prefix it (`agent-` or anything else).
32
+ In the same question suggest an **emoji** for it (e.g. 📺 for a YouTube agent, 📝 for a
33
+ writer) unless the task already says "Icon: …"; the sidebar shows its space as
34
+ `<emoji> <name>` (`--icon`, step 8). The user can pick another or none.
35
+
36
+ **The agent folder** (`$DIR` below):
37
+ - `$HIVEY_SETUP_CWD` when you're a setup pane, or your current folder, if it is empty or holds
38
+ only what the user put there for this agent.
39
+ - Otherwise `~/agents/<name>` (create it).
40
+ - Stop and ask if the folder is `$HOME`, a project with unrelated code, or already has a
41
+ `CLAUDE.md`/`AGENTS.md` (offer **Resume**, another folder, or replace).
42
+
43
+ ## 2. Understand the task
44
+
45
+ From the request, work out:
46
+ - **mission**: what the agent owns, and what it must not touch.
47
+ - **deliverables**: exact output paths, a "done when" for each and, where possible, a **check
48
+ command**: a shell command that exits 0 only when the deliverable really is done (`pytest -q`,
49
+ `test -s reports/latest.md && grep -q '## Sources' reports/latest.md`, a schema validator).
50
+ Runnable checks catch "claimed done but isn't", which prose criteria miss. Keep outputs out
51
+ of `dist/`, `build/`, `target/`, `.next/`, `.venv/`, `node_modules/`; use `reports/`,
52
+ `output/`, `data/` or similar.
53
+ - **the run check**: the deliverables' checks combined into one command that says "this run is
54
+ done", usually `bash scripts/check.sh` in the agent folder (written in step 6). It can back a
55
+ **done gate** (step 4). Make it strict about what matters, but able to pass on a legitimately
56
+ quiet run (e.g. a "nothing new" marker). For a builder it reads `tasks.json`.
57
+ - **one-shot or ongoing**: a job with an end, or a standing role (daily scans, a queue). Ongoing
58
+ agents need a cadence and a place to log each run.
59
+ - **coding agent and model** (step 3 asks):
60
+
61
+ | Kind (`--kind`) | Suggest it for | Model |
62
+ |---|---|---|
63
+ | `claude`, Claude Code (default) | most work: building, research, writing, ops; browser control | `opus` for code and deep reasoning; `sonnet` for research, writing, routine ops; `haiku` for trivial jobs |
64
+ | `codex`, Codex | code review, a second opinion from another model family | leave out to use the user's configured model |
65
+ | `grok`, Grok | X/Twitter and web research | `grok models` lists them |
66
+ | `agy`, Antigravity (Gemini) | fast, cheap tasks; image generation | see the `hivey-agy` skill's model table |
67
+
68
+ All four read the brief: you write `CLAUDE.md`, and launch links `AGENTS.md` (and `GEMINI.md`
69
+ for agy) to it. Only Claude Code gets hivey's safety hooks, the done gate and the reviewer
70
+ subagent; say so when you suggest another kind.
71
+ - **schedule** (ongoing agents): on demand only, an interval (`--heartbeat 6h`), or fixed times
72
+ (`hivey swarm schedule add <name> --at 08:57 …`). Draft the exact prompt each run gets.
73
+
74
+ If the request is too vague to fill these in, ask one short round of questions. Don't guess the
75
+ core job.
76
+
77
+ ## 3. Pick capabilities
78
+
79
+ **Skills.** Run `hivey skills guide` and follow it: skylls first (the user's and friends'
80
+ published skills), skills.sh only with the user's OK, and skills land in the agent's own
81
+ `$DIR/.claude/skills/`, never globally. Pick only skills the agent will use (usually 2 to 6):
82
+ each one costs context in every session. List **skill gaps** (needs no skill covers) as
83
+ suggestions; don't build them now. A non-Claude agent doesn't load `.claude/skills/` by itself:
84
+ its brief names each skill with its path (`.claude/skills/<skill>/SKILL.md`) and says when to
85
+ read it. Before designing from scratch, `skylls --json agents find <words> --limit 5` may show
86
+ the user or a friend already has this agent.
87
+
88
+ **MCP servers.** Only the ones the task really needs, and only with the user's OK. They go
89
+ **project-scoped** in `$DIR/.mcp.json`, so only this agent loads them; hivey installs none.
90
+ Library docs need none: the `hivey-context7` skill covers them. Prefer a CLI when one does the
91
+ job. Note which servers need an API key.
92
+
93
+ **Tools.**
94
+ - CLIs the job needs (`gh`, `ffmpeg`, `uv`, `yt-dlp`…): check each with `command -v` and list
95
+ the missing ones with an install command. Don't install system software unasked.
96
+ - Secrets: only from the user's secret store, fetched at the moment they're needed. The brief
97
+ names the key (or the command that fetches it), never the value. Never write a secret into
98
+ a file, prompt, message or commit, and never ask for one in chat.
99
+ - Permissions: hivey launches every agent with permissions pre-approved (Claude Code
100
+ `--dangerously-skip-permissions`, Codex without approvals or sandbox, Grok `--always-approve`,
101
+ agy `--dangerously-skip-permissions`). For Claude Code agents, hivey's **safety hooks** guard
102
+ that: check they're on with `hivey safety` (on by default; if off, tell the user, and don't
103
+ turn them on or off yourself). Add `deny` rules the job calls for (`Bash(git push:*)` is
104
+ always added: agents commit, they never push). If the agent touches money, production or
105
+ other people's accounts, say so in the plan and make its brief require asking first.
106
+ - Extra folders it may read or write: list them (`--dirs`); Grok can't take extra folders.
107
+
108
+ **Directory profile.** A one-line **description**, its **skills** and its **tools** (CLIs and
109
+ `mcp:<name>`). They go into `hivey swarm directory`, where other agents read them to decide
110
+ whether to ask this agent for help.
111
+
112
+ ## 4. Confirm the plan
113
+
114
+ Show the plan and wait for a yes before creating anything:
115
+
116
+ ```
117
+ Agent: <emoji> <name> — <one-line role> folder: <DIR>
118
+ Kind: one-shot | ongoing (<cadence>) runs on: Claude Code | Codex | Grok | agy, model <m> (<why>)
119
+ | # | Deliverable | Path | Done when / check |
120
+ Skills: <a> (why), <b> (why) gaps: <gap> → suggestion
121
+ MCPs: none | <x> (why, needs key: <name>) CLIs: <ok…> missing: <tool> → <install cmd>
122
+ Permissions: pre-approved + hivey safety on | (non-Claude: no safety hooks) deny: git push, <…>
123
+ Extra dirs: <paths>
124
+ Run check: <command> · done gate: yes | no · reviewer: yes | no (Claude Code only)
125
+ Memory: <name>-wiki | none
126
+ Slack: #<name> | none (Slack not connected)
127
+ Schedule: on demand | --heartbeat <6h> | at <HH:MM>, … → "<run prompt>"
128
+ Profile: "<description>" · skills <a,b> · tools <x,y>
129
+ ```
130
+
131
+ In the same message ask what you can't infer, one question at a time if you have no question
132
+ tool (AskUserQuestion in Claude Code; otherwise plain questions):
133
+ 1. **Coding agent and model**, with your suggestion first and why (step 2's table). If the user
134
+ already named one, don't ask.
135
+ 2. **Memory**: *Obsidian wiki* (`<DIR>/<name>-wiki/`, a Karpathy-style LLM wiki the agent
136
+ maintains, inside its own folder so the agent and its knowledge move and share as one
137
+ folder; best for research, domain and content agents whose knowledge compounds) or *none*
138
+ (the Status section is its only memory; fine for one-shot jobs). Never ask where the user's
139
+ Obsidian is.
140
+ 3. **Schedule** (ongoing agents only): your recommendation first. Runs happen only while hivey
141
+ runs; each wake-up arrives as a `[hivey]` message when the agent is idle, never piles up and
142
+ never expires.
143
+ 4. **Done gate and reviewer** (Claude Code only): propose the reviewer when the output can be
144
+ checked against sources or specs and a second read is worth the tokens; leave it out for
145
+ routine ops.
146
+
147
+ **Slack is not a question.** Run `hivey slack status`. Connected: launch creates (or joins)
148
+ `#<name>`, invites the user and starts the relay. Not connected: ask the user to run `hivey
149
+ slack connect` in a terminal (never ask for the token in chat), or go on without Slack if
150
+ they'd rather not.
151
+
152
+ Adjust the plan if the user tweaks it; continue once they approve.
153
+
154
+ ## 5. Scaffold the folder
155
+
156
+ ```bash
157
+ python3 $A/setup_agent.py "$DIR" --name <name> --kind <claude|codex|grok|agy> \
158
+ [--dirs /extra/path,…] [--allow 'Bash(gh:*)'] [--deny 'Bash(rm:*)'] \
159
+ [--mcp '<server>={"command":"npx","args":["-y","<pkg>"]}'] \
160
+ [--check-cmd 'bash scripts/check.sh'] [--gate] [--reviewer] [--git]
161
+ ```
162
+
163
+ It is idempotent (re-running only adds) and prints JSON. It writes:
164
+ - a `CLAUDE.md` skeleton if there's none (sections and the Status markers; step 6 fills it);
165
+ - `.claude/settings.json` in the agent folder: `additionalDirectories` (the folder plus
166
+ `--dirs`; launch turns them into `--add-dir`), `allow`/`deny` rules (`Bash(git push:*)` always
167
+ denied) and, for MCP servers, `enabledMcpjsonServers` so no approval dialog blocks startup;
168
+ - `.mcp.json` with each `--mcp` server (`--enable-mcps x,y` pre-approves servers already in
169
+ it). For a Codex agent the same servers are copied into `.codex/config.toml`. Grok and agy:
170
+ set up MCP servers with their own CLI if really needed, or prefer a CLI tool;
171
+ - `.agent/config.json` with the run check; with `--gate` (Claude Code) the **done gate** and
172
+ **resume context** hooks are registered in the agent's own `.claude/settings.json`, never the
173
+ global one; `--reviewer` installs the read-only `reviewer` subagent in `.claude/agents/`;
174
+ - `.gitignore` (keeps `.mcp.json`, `.codex/`, `.agent/state/`, `logs/` out of git) and, with
175
+ `--git`, a git repo in the folder if it isn't in one.
176
+
177
+ Then install the skills as `hivey skills guide` says, from `$DIR`, and check `ls
178
+ $DIR/.claude/skills`. For keys an MCP server needs, the user puts them in `.mcp.json` (or the
179
+ environment) from their secret store; tell them which servers hold a key (the file is
180
+ git-ignored).
181
+
182
+ The harness, when chosen:
183
+
184
+ | Piece | What it does |
185
+ |---|---|
186
+ | Done gate | Stop hook `agent_gate.py`: while `.agent/state/run_active` exists, runs the check when the agent tries to finish and blocks it (at most 3 times), logging to `.agent/state/gate.log` |
187
+ | Resume context | SessionStart hook `agent_context.py`: on startup, resume and compaction injects run-in-progress, gate log, `tasks.json` progress, recent commits and the newest progress-log entries |
188
+ | Reviewer | `.claude/agents/reviewer.md`: read-only subagent (Sonnet) that checks artifacts against The ask and their sources |
189
+
190
+ The hooks point at this skill's scripts, so improving them upgrades every agent. Codex, Grok
191
+ and agy agents run the check themselves (the template says how).
192
+
193
+ ## 6. Write the CLAUDE.md
194
+
195
+ Read `references/agent-claude-md.md` now: it has the template and guidance per agent type.
196
+ Write `$DIR/CLAUDE.md` (replace the skeleton):
197
+ 1. For agents that write code, start with the general guidelines block: copy
198
+ `references/global-guidelines.md` verbatim (it carries its own `<!-- BEGIN GUIDELINES -->`
199
+ and `<!-- END GUIDELINES -->` markers).
200
+ 2. Then the agent's own brief from the template: mission, deliverables each with a runnable
201
+ check, method, rules (secrets, safety, docs with `hivey-context7` first, asking before
202
+ anything destructive or outward-facing), memory, and the dated **Status** section it rewrites
203
+ so a fresh session can resume.
204
+
205
+ Make it detailed and specific: quote the user's request verbatim, use absolute paths, name each
206
+ skill and MCP with when to use it, and include the runnable checks. The agent reads this cold.
207
+ A vague brief produces a vague agent.
208
+
209
+ **But keep it short.** Long briefs get partly ignored.
210
+ - Keep the agent's own part to about **150 lines**: `awk '/<!-- END GUIDELINES -->/{f=1;next} f'
211
+ CLAUDE.md | wc -l` (or `wc -l CLAUDE.md` without the block).
212
+ - Keep Method to the essential steps; put the full method, examples and edge cases in
213
+ `$DIR/METHOD.md` and have the brief say "read METHOD.md before every run".
214
+ - Put hard rules in settings, the check command and the gate, not only in prose.
215
+
216
+ Also write, in this step:
217
+ - `scripts/check.sh`: the run check. Executable, exit 0 only when a run is really done. Run it
218
+ once now: it should fail cleanly before the first run.
219
+ - `tasks.json` for builder agents (format in the template).
220
+
221
+ Keep the template's **Schedule** section only if there's a schedule and its **Slack** section
222
+ only if Slack is connected; otherwise delete them and their checklist lines.
223
+
224
+ ## 7. Memory (if the user chose a wiki)
225
+
226
+ After `CLAUDE.md` exists, invoke the `hivey-create-wiki` skill with args `<name> --in "$DIR"`.
227
+ It creates `$DIR/<name>-wiki/`, tailors it to the brief and patches the brief with a wiki
228
+ section. Answer its questions yourself from the plan. Then check that the template's Memory
229
+ section and the patched section agree (keep one). Tell the user the vault path.
230
+
231
+ ## 8. Launch
232
+
233
+ ```bash
234
+ hivey swarm launch "$DIR" --slug <name> --icon <emoji> --solo --kind <claude|codex|grok|agy> [--model <m>] \
235
+ --description "<one line>" --skills a,b --tools "gh, mcp:x" \
236
+ [--heartbeat 6h --heartbeat-task "Start a run (Run protocol): <run prompt>"] \
237
+ [--kickoff "<first concrete task>"]
238
+ ```
239
+
240
+ The agent opens in a **new space `<emoji> <name>`** with a ★ row in the sidebar, as its own master.
241
+ Your pane stays where it is. With Slack connected, launch creates `#<name>` and its relay; add
242
+ `--slack` to make a missing connection an error, `--no-slack` to skip it.
243
+
244
+ Fixed-time runs, one entry per time (`--at` is daily):
245
+ ```bash
246
+ hivey swarm schedule add <name> --at 08:57 --id morning "Start a run (Run protocol): <run prompt>"
247
+ hivey swarm schedule add <name> --every 30m --id check "<task>"
248
+ hivey swarm schedule list <name>
249
+ ```
250
+ No cron, `/loop` or CronCreate: hivey wakes the agent.
251
+
252
+ **Verify it started.** `hivey swarm info <name>`, then `hivey pane read <pane> --source visible`
253
+ (pane from `hivey swarm list`): it should have read its brief and restated its task correctly.
254
+ If it waits on a dialog, answer it or tell the user. If it misread the task, correct it now
255
+ with `hivey msg send <name>/master "…"`: a wrong assumption fixed in minute one saves an hour.
256
+
257
+ ## 9. Summary
258
+
259
+ ```
260
+ Agent "<name>" created
261
+ Runs on: Claude Code | Codex | Grok | agy (<model>)
262
+ Folder: <DIR> CLAUDE.md: <n> agent lines (+ METHOD.md <n> lines)
263
+ Skills: <list> (gaps: …)
264
+ MCPs: <list> | none (keys in .mcp.json for: …)
265
+ Memory: <DIR>/<name>-wiki | none
266
+ Slack: #<name> | none
267
+ Schedule: on demand | heartbeat <6h> | at <times>
268
+ Harness: check `<cmd>` · done gate · resume context · reviewer | none
269
+ Space: <emoji> <name> (★ in the sidebar)
270
+ Talk to it: hivey msg send <name>/master "…" (or in #<name>)
271
+ Relaunch: hivey swarm relaunch <name>
272
+ Profile: hivey swarm profile <name> --description … --skills … --tools …
273
+ Saved: skylls agents push (v<n>) | not saved
274
+ ```
275
+
276
+ Tell the user they can close this designer tab.
277
+
278
+ ## 10. Save and share (skylls)
279
+
280
+ If `skylls --version` works, offer to save the agent so the user can reuse and share it. Only
281
+ with their yes: `skylls agents push "$DIR" -m "<what it does>"` (it takes the agent's memory
282
+ along), plus `skylls push <skill folder>` for any new skill you wrote. Push scans for secrets
283
+ and personal data and refuses if it finds any: remove them, never pass `--skip-scan`. Share
284
+ (`skylls agents share <name> @user`) only when the user asks.
285
+
286
+ ## Resume and change
287
+
288
+ If the folder already has a `CLAUDE.md` and the user wants that agent back, don't redesign it:
289
+ read the brief (including Status) and run `hivey swarm relaunch <name>` (it continues the
290
+ conversation; `hivey swarm register "$DIR"` first if it was unregistered). To change it, edit
291
+ the relevant brief sections and rerun `setup_agent.py` for new permissions, MCPs or the
292
+ harness (idempotent), then update its directory entry with `hivey swarm profile`. To add a
293
+ schedule later, use `hivey swarm schedule add` and add the template's Schedule section. To add
294
+ Slack later, `hivey slack add <name>`.
295
+
296
+ ## Rules for you, the designer
297
+
298
+ - Confirm the plan before creating anything; ask before anything destructive or outward-facing.
299
+ - Only touch the agent folder (and the extra folders the plan names).
300
+ - Never edit the global `~/.claude/settings.json`, global skills or other agents' folders.
301
+ - If a safety hook blocks you, ask the user; never work around it or turn safety off.
302
+ - Look up any library, API or CLI docs you need with the `hivey-context7` skill first.
303
+ - End your final message with `DONE: <3 words max>` on its own line.