@hivey/cli 0.0.0-stage → 0.9.36
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +235 -2
- package/bin/hivey.js +98 -0
- package/native/darwin-arm64/hivey +0 -0
- package/package.json +36 -4
- package/platforms.json +3 -0
- package/repo/LICENSE +201 -0
- package/repo/NOTICE +18 -0
- package/repo/README.md +148 -0
- package/repo/install.sh +365 -0
- package/repo/pets/README.md +25 -0
- package/repo/pets/hivey-dot/CLAUDE.md +55 -0
- package/repo/pets/hivey-dot/build.sh +34 -0
- package/repo/pets/hivey-dot/main.swift +750 -0
- package/repo/pets/hivey-h/CLAUDE.md +75 -0
- package/repo/pets/hivey-h/build.sh +34 -0
- package/repo/pets/hivey-h/main.swift +739 -0
- package/repo/pets/hivey-prompt/CLAUDE.md +59 -0
- package/repo/pets/hivey-prompt/build.sh +34 -0
- package/repo/pets/hivey-prompt/main.swift +691 -0
- package/repo/pets/pet.py +288 -0
- package/repo/pets/shared/HiveyWatch.swift +437 -0
- package/repo/pets/test_pet.py +122 -0
- package/repo/plugins/README.md +108 -0
- package/repo/plugins/agent-creator/herdr-plugin.toml +17 -0
- package/repo/plugins/dashboard/dashboard.py +507 -0
- package/repo/plugins/dashboard/herdr-plugin.toml +14 -0
- package/repo/plugins/dashboard/test_dashboard.py +134 -0
- package/repo/plugins/github/github.py +261 -0
- package/repo/plugins/github/herdr-plugin.toml +14 -0
- package/repo/plugins/github/test_github.py +49 -0
- package/repo/plugins/skills/herdr-plugin.toml +11 -0
- package/repo/plugins/skills/skills.md +41 -0
- package/repo/plugins/slack-relay/connect.py +198 -0
- package/repo/plugins/slack-relay/create_channel.py +134 -0
- package/repo/plugins/slack-relay/herdr-plugin.toml +15 -0
- package/repo/plugins/slack-relay/relay.py +401 -0
- package/repo/plugins/slack-relay/slack-app-manifest.json +30 -0
- package/repo/plugins/slack-relay/test_connect.py +66 -0
- package/repo/plugins/slack-relay/test_create_channel.py +61 -0
- package/repo/plugins/slack-relay/test_relay.py +254 -0
- package/repo/plugins/swarm-creator/herdr-plugin.toml +17 -0
- package/repo/plugins/swarm-watcher/dashboard.py +333 -0
- package/repo/plugins/swarm-watcher/herdr-plugin.toml +16 -0
- package/repo/plugins/swarm-watcher/usage.py +129 -0
- package/repo/plugins/swarm-watcher/watcher.py +191 -0
- package/repo/plugins/team-template/herdr-plugin.toml +15 -0
- package/repo/plugins/team-template/setup.py +211 -0
- package/repo/plugins/team-template/test_setup.py +73 -0
- package/repo/plugins/tts/herdr-plugin.toml +15 -0
- package/repo/skills/herdr/SKILL.md +214 -0
- package/repo/skills/hivey/SKILL.md +322 -0
- package/repo/skills/hivey/scripts/handoff.py +27 -0
- package/repo/skills/hivey/scripts/new_wiki.py +143 -0
- package/repo/skills/hivey-agent-creator/SKILL.md +303 -0
- package/repo/skills/hivey-agent-creator/references/agent-claude-md.md +256 -0
- package/repo/skills/hivey-agent-creator/references/global-guidelines.md +67 -0
- package/repo/skills/hivey-agent-creator/references/reviewer-agent.md +35 -0
- package/repo/skills/hivey-agent-creator/scripts/agent_context.py +76 -0
- package/repo/skills/hivey-agent-creator/scripts/agent_gate.py +78 -0
- package/repo/skills/hivey-agent-creator/scripts/setup_agent.py +288 -0
- package/repo/skills/hivey-agy/SKILL.md +123 -0
- package/repo/skills/hivey-agy/references/gemini-prompting.md +134 -0
- package/repo/skills/hivey-agy/scripts/agy_run.py +146 -0
- package/repo/skills/hivey-codex/SKILL.md +66 -0
- package/repo/skills/hivey-context7/SKILL.md +56 -0
- package/repo/skills/hivey-create-wiki/SKILL.md +329 -0
- package/repo/skills/hivey-grok/SKILL.md +101 -0
- package/repo/skills/hivey-grok/scripts/grok_run.py +139 -0
- package/repo/skills/hivey-swarm-creator/SKILL.md +384 -0
- package/repo/skills/hivey-swarm-creator/references/agent-claude-md.md +313 -0
- package/repo/skills/hivey-swarm-creator/references/archify-report.md +24 -0
- package/repo/skills/hivey-swarm-creator/references/dashboard.md +46 -0
- package/repo/skills/hivey-swarm-creator/references/retrospective.md +23 -0
- package/repo/skills/hivey-swarm-creator/references/shared-rules.md +39 -0
- package/repo/skills/hivey-swarm-creator/references/wiki-memory.md +30 -0
- package/repo/skills/hivey-swarm-creator/scripts/setup_agent.py +76 -0
- package/repo/skills/hivey-swarm-creator/scripts/shared_rules.py +50 -0
- package/repo/skills/hivey-swarm-creator/scripts/swarm_tasks.py +171 -0
- package/repo/skills/hivey-wiki-ingest/SKILL.md +45 -0
- package/repo/skills/hivey-wiki-lint/SKILL.md +38 -0
- package/repo/skills/hivey-wiki-list/SKILL.md +46 -0
- package/repo/skills/hivey-wiki-log/SKILL.md +45 -0
- package/repo/skills/hivey-wiki-query/SKILL.md +44 -0
|
@@ -0,0 +1,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.
|