@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,146 @@
|
|
|
1
|
+
#!/usr/bin/env -S uv run --script
|
|
2
|
+
# /// script
|
|
3
|
+
# requires-python = ">=3.11"
|
|
4
|
+
# dependencies = []
|
|
5
|
+
# ///
|
|
6
|
+
"""Run the Antigravity CLI (agy) headless from Python.
|
|
7
|
+
|
|
8
|
+
Examples:
|
|
9
|
+
agy_run.py "What is git rebase?"
|
|
10
|
+
agy_run.py -m claude-opus-4-6-thinking -e high "Explain this repo" --cwd ~/projects/hivey
|
|
11
|
+
agy_run.py -m gemini-3.1-pro-high --schema '{"type":"object","properties":{"major":{"type":"integer"}}}' "Parse v2.14.3"
|
|
12
|
+
echo "long prompt" | agy_run.py -
|
|
13
|
+
agy_run.py --chat -m gemini-3.8-flash-high # multi-turn session over stream-json
|
|
14
|
+
agy_run.py --cwd ~/out --yolo --expect cat.png "Generate ... save as cat.png"
|
|
15
|
+
agy_run.py --models # list model slugs
|
|
16
|
+
"""
|
|
17
|
+
import argparse
|
|
18
|
+
import json
|
|
19
|
+
import os
|
|
20
|
+
import subprocess
|
|
21
|
+
import sys
|
|
22
|
+
from pathlib import Path
|
|
23
|
+
|
|
24
|
+
AGY = os.environ.get("AGY_BIN", str(Path.home() / ".local/bin/agy"))
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def base_cmd(a) -> list[str]:
|
|
28
|
+
cmd = [AGY]
|
|
29
|
+
if a.model:
|
|
30
|
+
cmd += ["--model", a.model]
|
|
31
|
+
if a.effort:
|
|
32
|
+
cmd += ["--effort", a.effort]
|
|
33
|
+
if a.agent:
|
|
34
|
+
cmd += ["--agent", a.agent]
|
|
35
|
+
if a.yolo:
|
|
36
|
+
cmd += ["--dangerously-skip-permissions"]
|
|
37
|
+
if a.sandbox:
|
|
38
|
+
cmd += ["--sandbox"]
|
|
39
|
+
if a.cont:
|
|
40
|
+
cmd += ["--continue"]
|
|
41
|
+
if a.conversation:
|
|
42
|
+
cmd += ["--conversation", a.conversation]
|
|
43
|
+
return cmd
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def ask(a, prompt: str) -> dict:
|
|
47
|
+
"""One headless turn; returns the JSON envelope (response, status, usage, ...)."""
|
|
48
|
+
cmd = base_cmd(a) + ["-p", prompt, "--output-format", "json", "--print-timeout", a.timeout]
|
|
49
|
+
if a.schema:
|
|
50
|
+
cmd += ["--json-schema", a.schema]
|
|
51
|
+
p = subprocess.run(cmd, capture_output=True, text=True, cwd=a.cwd)
|
|
52
|
+
try:
|
|
53
|
+
return json.loads(p.stdout)
|
|
54
|
+
except json.JSONDecodeError:
|
|
55
|
+
return {"status": "ERROR", "error": (p.stderr or p.stdout).strip(), "exit_code": p.returncode}
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def chat(a) -> None:
|
|
59
|
+
"""Multi-turn session: one agy process, prompts as NDJSON on stdin."""
|
|
60
|
+
cmd = base_cmd(a) + ["--input-format", "stream-json", "--output-format", "stream-json"]
|
|
61
|
+
proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True, bufsize=1, cwd=a.cwd)
|
|
62
|
+
try:
|
|
63
|
+
while True:
|
|
64
|
+
try:
|
|
65
|
+
msg = input("you> ").strip()
|
|
66
|
+
except EOFError:
|
|
67
|
+
break
|
|
68
|
+
if msg in ("", "exit", "quit"):
|
|
69
|
+
break
|
|
70
|
+
proc.stdin.write(json.dumps({"event": "user", "message": {"content": msg}}) + "\n")
|
|
71
|
+
proc.stdin.flush()
|
|
72
|
+
for line in proc.stdout:
|
|
73
|
+
ev = json.loads(line)
|
|
74
|
+
step = ev.get("step_update") or {}
|
|
75
|
+
if step.get("text_delta"):
|
|
76
|
+
print(step["text_delta"], end="", flush=True)
|
|
77
|
+
elif ev.get("event") == "result":
|
|
78
|
+
r = ev["result"]
|
|
79
|
+
if r.get("status") != "SUCCESS":
|
|
80
|
+
print(f"\n[{r.get('status')}] {r.get('error', '')}", file=sys.stderr)
|
|
81
|
+
print()
|
|
82
|
+
break
|
|
83
|
+
finally:
|
|
84
|
+
proc.stdin.close()
|
|
85
|
+
proc.wait()
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def main() -> int:
|
|
89
|
+
ap = argparse.ArgumentParser(description="Run agy (Antigravity CLI) headless")
|
|
90
|
+
ap.add_argument("prompt", nargs="?", help="prompt text, or '-' to read stdin")
|
|
91
|
+
ap.add_argument("-m", "--model", help="model slug (see --models)")
|
|
92
|
+
ap.add_argument("-e", "--effort", choices=["low", "medium", "high"])
|
|
93
|
+
ap.add_argument("--agent")
|
|
94
|
+
ap.add_argument("--schema", help="JSON schema (string, .json path, or string/number/integer/boolean)")
|
|
95
|
+
ap.add_argument("--cwd", type=lambda s: str(Path(s).expanduser()), help="workspace dir for the agent")
|
|
96
|
+
ap.add_argument("--timeout", default="10m", help="--print-timeout (e.g. 5m, 0s = no limit)")
|
|
97
|
+
ap.add_argument("--yolo", action="store_true", help="--dangerously-skip-permissions")
|
|
98
|
+
ap.add_argument("--sandbox", action="store_true")
|
|
99
|
+
ap.add_argument("-c", "--continue", dest="cont", action="store_true", help="continue last conversation")
|
|
100
|
+
ap.add_argument("--conversation", help="resume conversation id")
|
|
101
|
+
ap.add_argument("--json", action="store_true", help="print the full JSON envelope")
|
|
102
|
+
ap.add_argument("--expect", action="append", default=[], metavar="FILE",
|
|
103
|
+
help="file the run must create (relative to --cwd); exit 3 if missing. agy can say SUCCESS when a tool failed")
|
|
104
|
+
ap.add_argument("--chat", action="store_true", help="interactive multi-turn via stream-json")
|
|
105
|
+
ap.add_argument("--models", action="store_true", help="list model slugs and exit")
|
|
106
|
+
a = ap.parse_args()
|
|
107
|
+
|
|
108
|
+
if a.models:
|
|
109
|
+
return subprocess.run([AGY, "models"]).returncode
|
|
110
|
+
if a.chat:
|
|
111
|
+
chat(a)
|
|
112
|
+
return 0
|
|
113
|
+
if not a.prompt:
|
|
114
|
+
ap.error("prompt required (or --chat / --models)")
|
|
115
|
+
prompt = sys.stdin.read() if a.prompt == "-" else a.prompt
|
|
116
|
+
|
|
117
|
+
r = ask(a, prompt)
|
|
118
|
+
denied = r.get("denied_actions") or []
|
|
119
|
+
if denied:
|
|
120
|
+
names = ", ".join(d.get("action", "?") for d in denied)
|
|
121
|
+
print(f"[DENIED] agy was not allowed to: {names} (rerun with --yolo, or allow them in "
|
|
122
|
+
"~/.gemini/antigravity-cli/settings.json)", file=sys.stderr)
|
|
123
|
+
if r.get("status") == "SUCCESS" and not (r.get("response") or "").strip() and r.get("structured_output") is None:
|
|
124
|
+
r["status"] = "EMPTY"
|
|
125
|
+
r.setdefault("error", "agy finished without an answer" + (" (actions were denied)" if denied else ""))
|
|
126
|
+
if a.json:
|
|
127
|
+
print(json.dumps(r, indent=2, ensure_ascii=False))
|
|
128
|
+
elif r.get("status") == "SUCCESS":
|
|
129
|
+
out = r.get("structured_output")
|
|
130
|
+
print(json.dumps(out, indent=2, ensure_ascii=False) if out is not None else r.get("response", ""))
|
|
131
|
+
else:
|
|
132
|
+
print(f"[{r.get('status')}] {r.get('error', '')}", file=sys.stderr)
|
|
133
|
+
if r.get("status") == "EMPTY":
|
|
134
|
+
return 4
|
|
135
|
+
if r.get("status") != "SUCCESS":
|
|
136
|
+
return 1
|
|
137
|
+
base = Path(a.cwd or ".")
|
|
138
|
+
missing = [f for f in a.expect if not (base / Path(f).expanduser()).exists()]
|
|
139
|
+
if missing:
|
|
140
|
+
print(f"[MISSING] expected file(s) not created: {', '.join(missing)}", file=sys.stderr)
|
|
141
|
+
return 3
|
|
142
|
+
return 0
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
if __name__ == "__main__":
|
|
146
|
+
sys.exit(main())
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hivey-codex
|
|
3
|
+
description: >
|
|
4
|
+
Run a task with OpenAI's Codex CLI (`codex`) headless from the shell with `codex exec`: coding
|
|
5
|
+
work in a folder, code review, research, quick answers or structured JSON extraction, with the
|
|
6
|
+
right model, sandbox and output options, then check the result. Also resumes or forks earlier
|
|
7
|
+
Codex sessions. Use whenever the user wants something done "with Codex", "ask Codex", "codex
|
|
8
|
+
exec", wants a Codex / GPT second opinion or review, or hands a task to Codex, even if they
|
|
9
|
+
don't say "CLI". Not for the ChatGPT app or for calling the OpenAI API from code.
|
|
10
|
+
allowed-tools:
|
|
11
|
+
- Bash
|
|
12
|
+
- Read
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
> Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
|
|
16
|
+
> It holds this machine's own additions; hivey updates never touch it, so put local changes
|
|
17
|
+
> there, never here.
|
|
18
|
+
|
|
19
|
+
# hivey codex: run Codex headless
|
|
20
|
+
|
|
21
|
+
`codex exec` runs one Codex task without the interactive UI and exits when it's done: the
|
|
22
|
+
final message goes to stdout (progress to stderr). Check `codex --version`; install with
|
|
23
|
+
`bun install -g @openai/codex` (or npm), sign in once with `codex login`.
|
|
24
|
+
|
|
25
|
+
## Run a task
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
codex exec -C <folder> -s workspace-write -o /tmp/codex-answer.md "<prompt>"
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
- `-C, --cd <DIR>`: the folder Codex works in (its root). `--add-dir <DIR>` lets it write more.
|
|
32
|
+
- `-s, --sandbox`: `read-only` (answers, reviews, research), `workspace-write` (edits in the
|
|
33
|
+
folder; the usual choice for coding), `danger-full-access` (only when asked).
|
|
34
|
+
- `--approve-for-me`: approvals reviewed automatically, with `workspace-write`.
|
|
35
|
+
`--dangerously-bypass-approvals-and-sandbox` only in a sandboxed environment the user set up.
|
|
36
|
+
- `-m, --model <MODEL>`: leave it out to use the user's configured model; set it when they
|
|
37
|
+
ask for one. Effort: `-c model_reasoning_effort="low|medium|high|xhigh"` (low for quick
|
|
38
|
+
answers, high for hard coding or review).
|
|
39
|
+
- `-o, --output-last-message <FILE>`: also write the final message to a file; read it after.
|
|
40
|
+
- `--json`: one JSON event per line on stdout (to follow tool calls and the session id).
|
|
41
|
+
- `--output-schema <FILE>`: the final answer must match this JSON Schema (extraction).
|
|
42
|
+
- `-i, --image <FILE>`: attach images. `--skip-git-repo-check`: run outside a git repo.
|
|
43
|
+
- `--ephemeral`: don't keep the session. `-p, --profile <name>`: a config profile.
|
|
44
|
+
- The prompt can come on stdin: `cat brief.md | codex exec -`.
|
|
45
|
+
|
|
46
|
+
## Review, resume, fork
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
codex exec review # review the current repository's changes
|
|
50
|
+
codex exec resume --last "<follow-up>" # continue the latest session in this folder
|
|
51
|
+
codex exec resume <SESSION_ID> "<follow-up>"
|
|
52
|
+
codex exec fork <SESSION_ID> "<prompt>" # a new session from an earlier one
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Writing the prompt
|
|
56
|
+
|
|
57
|
+
Say the goal, the files or folder, constraints (don't touch X, keep the API), and what "done"
|
|
58
|
+
means (tests pass, a file exists). Ask for a short summary of what changed at the end. For
|
|
59
|
+
long briefs, write them to a file and pipe it in.
|
|
60
|
+
|
|
61
|
+
## Check the result
|
|
62
|
+
|
|
63
|
+
Never pass Codex's answer on unchecked: read the `-o` file, look at `git diff` (or the files it
|
|
64
|
+
should have made), run the tests or the check the task named, and report what Codex did, what
|
|
65
|
+
you verified and anything that failed. On a non-zero exit, show the error (stderr) and the
|
|
66
|
+
likely cause (not signed in, sandbox refused a write, no git repo).
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hivey-context7
|
|
3
|
+
description: >
|
|
4
|
+
Look up current documentation for any library, framework, SDK, API, CLI or cloud service in
|
|
5
|
+
seconds with Context7 (context7.com), straight from the shell: find the library, then fetch
|
|
6
|
+
the docs and code snippets for the exact question. Works in every agent hivey runs (Claude
|
|
7
|
+
Code, Codex, Grok, Antigravity) with no MCP setup. Use it FIRST whenever you need API syntax,
|
|
8
|
+
configuration, setup steps, version changes or library-specific debugging, even for
|
|
9
|
+
well-known libraries (React, Next.js, Expo, Prisma, Tailwind, Django…): your training data
|
|
10
|
+
may be out of date. Not for general programming concepts or the user's own code.
|
|
11
|
+
allowed-tools:
|
|
12
|
+
- Bash
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
> Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
|
|
16
|
+
> It holds this machine's own additions; hivey updates never touch it, so put local changes
|
|
17
|
+
> there, never here.
|
|
18
|
+
|
|
19
|
+
# hivey context7: fast, current docs
|
|
20
|
+
|
|
21
|
+
Context7 serves up-to-date documentation and code snippets for thousands of libraries, picked
|
|
22
|
+
for a question. It is faster and more precise than a web search for library docs, so use it
|
|
23
|
+
before searching the web or guessing from memory.
|
|
24
|
+
|
|
25
|
+
## 1. Find the library ID
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
curl -s "https://context7.com/api/v2/libs/search?libraryName=<library>&query=<what you need>" \
|
|
29
|
+
${CONTEXT7_API_KEY:+-H "Authorization: Bearer $CONTEXT7_API_KEY"}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The JSON `results` list each library's `id` (e.g. `/vercel/next.js`), `title`, `description`,
|
|
33
|
+
`totalSnippets` and `trustScore`. Pick the official one (highest trust and snippets, matching
|
|
34
|
+
title). Skip this step when you already know the ID, or when the user gave one
|
|
35
|
+
(`/org/project`, optionally `/org/project/<version>`).
|
|
36
|
+
|
|
37
|
+
## 2. Fetch the docs for the question
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
curl -s "https://context7.com/api/v2/context?libraryId=<id>&query=<specific question>&type=txt" \
|
|
41
|
+
${CONTEXT7_API_KEY:+-H "Authorization: Bearer $CONTEXT7_API_KEY"}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Plain text: titled snippets with their source URL and code. URL-encode the query (spaces as
|
|
45
|
+
`%20`). Make the query specific ("app router root layout", not "next.js"): the snippets are
|
|
46
|
+
chosen for it. Ask again with another query for another part of the answer. `type=json`
|
|
47
|
+
returns `codeSnippets` and `infoSnippets` instead.
|
|
48
|
+
|
|
49
|
+
## Rules
|
|
50
|
+
|
|
51
|
+
- Answer from what Context7 returns and cite the source URLs it gives. If it has nothing
|
|
52
|
+
useful, say so, then fall back to the library's official docs on the web.
|
|
53
|
+
- Without an API key the rate limit is low: on HTTP `429`, wait for `Retry-After` seconds. A
|
|
54
|
+
key (free at context7.com) goes in `CONTEXT7_API_KEY` (from the user's secret store, never
|
|
55
|
+
written into a file or prompt).
|
|
56
|
+
- Never send private code, secrets or personal data in a query: it goes to context7.com.
|
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hivey-create-wiki
|
|
3
|
+
description: >
|
|
4
|
+
Create the Obsidian wiki of a hivey agent or swarm (LLM Wiki pattern, Karpathy): a
|
|
5
|
+
<name>-wiki/ vault inside the agent's or swarm's own folder with raw/ + wiki/, a CLAUDE.md
|
|
6
|
+
schema tailored to the agent's domain, index.md and log.md, and a section in the agent's
|
|
7
|
+
CLAUDE.md (each swarm agent's) pointing at it. Only for agents and swarms. Use whenever the
|
|
8
|
+
user wants a wiki, a knowledge base or long-term memory for an agent or a swarm ("create
|
|
9
|
+
wiki", "new wiki", "wiki for <agent>", "/hivey-create-wiki"), and whenever an agent or swarm
|
|
10
|
+
creator sets up its memory.
|
|
11
|
+
argument-hint: <agent-or-swarm-name> [--in <folder>] [--agent <dir>]...
|
|
12
|
+
allowed-tools:
|
|
13
|
+
- Bash
|
|
14
|
+
- Read
|
|
15
|
+
- Write
|
|
16
|
+
- Edit
|
|
17
|
+
- Glob
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
> Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
|
|
21
|
+
> It holds this machine's own additions; hivey updates never touch it, so put local changes
|
|
22
|
+
> there, never here.
|
|
23
|
+
|
|
24
|
+
# hivey create wiki
|
|
25
|
+
|
|
26
|
+
Scaffold the Obsidian wiki vault of a hivey agent or swarm, following Andrej
|
|
27
|
+
Karpathy's [LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
|
|
28
|
+
|
|
29
|
+
The wiki is a **persistent, compounding knowledge artifact** that an LLM maintains over time,
|
|
30
|
+
separate from the agent's operational state. Sources go into `raw/` (read-only), the LLM writes
|
|
31
|
+
synthesised pages into `wiki/`, and `index.md` + `log.md` track the catalog and history.
|
|
32
|
+
|
|
33
|
+
## Arguments
|
|
34
|
+
|
|
35
|
+
`$ARGUMENTS`: the **agent or swarm name** (e.g. `btc`, `gap-finder`), then optional flags:
|
|
36
|
+
|
|
37
|
+
- `--in <folder>`: the agent's or swarm's folder; the vault is created at
|
|
38
|
+
`<folder>/<slug>-wiki/`, next to the agents that use it, so the agent or swarm and its
|
|
39
|
+
knowledge travel together and can be shared as one folder. **Default when the current
|
|
40
|
+
folder (or one given by the caller) has a `CLAUDE.md`:** `--in .`. Agent and swarm creators
|
|
41
|
+
always pass it; never ask the user where their Obsidian is.
|
|
42
|
+
- `--agent <dir>` (repeatable): agent folders whose `CLAUDE.md` gets the wiki section (a
|
|
43
|
+
swarm's agents). With `--in` and no `--agent`, the folder's own `CLAUDE.md` is patched when
|
|
44
|
+
it exists.
|
|
45
|
+
This skill only makes wikis for agents and swarms. With no `--in` and no `CLAUDE.md` in the
|
|
46
|
+
current folder, ask which agent or swarm folder the wiki is for (it must have a `CLAUDE.md`,
|
|
47
|
+
or be a swarm root with agent folders); don't create a wiki that belongs to no agent.
|
|
48
|
+
|
|
49
|
+
If no name is given, use the folder's name; the hivey agent's folder `~/.hivey/agent` is named
|
|
50
|
+
`hivey` (its wiki is `~/.hivey/agent/hivey-wiki`).
|
|
51
|
+
|
|
52
|
+
Why `<slug>-wiki`: Obsidian lists vaults by folder name, so each wiki gets its own name in the
|
|
53
|
+
vault switcher. Older hivey vaults are called `obsidian/`; `hivey migrate` renames them. The
|
|
54
|
+
wiki skills (`/hivey-wiki-ingest`, `/hivey-wiki-query`, `/hivey-wiki-lint`,
|
|
55
|
+
`/hivey-wiki-log`, `/hivey-wiki-list`; `$hivey-wiki-ingest`, … in Codex) find the nearest `<slug>-wiki/` with a `CLAUDE.md`,
|
|
56
|
+
walking up from the current folder.
|
|
57
|
+
|
|
58
|
+
## Solo agent or swarm (detected, never asked)
|
|
59
|
+
|
|
60
|
+
- **Solo agent**: the folder has a `CLAUDE.md` and no `--agent` folders: one brief to read
|
|
61
|
+
and patch, the vault at `<folder>/<slug>-wiki/`.
|
|
62
|
+
- **Swarm**: `--agent` folders were given (or the folder's sub-folders have their own
|
|
63
|
+
`CLAUDE.md`): read the root's and every agent's brief, one shared vault at
|
|
64
|
+
`<root>/<slug>-wiki/`, every agent's brief patched with `../<slug>-wiki/…` paths.
|
|
65
|
+
|
|
66
|
+
## Step 1: Validate
|
|
67
|
+
|
|
68
|
+
1. Slugify the name: lowercase, hyphenated, no surrounding whitespace. Reject a path
|
|
69
|
+
separator, a leading dot, or an empty result. Drop a trailing `-wiki` (it is added).
|
|
70
|
+
2. If `<folder>/<slug>-wiki/CLAUDE.md` (or an older `<folder>/obsidian/CLAUDE.md`) already
|
|
71
|
+
exists, say the wiki exists and stop. Never overwrite: it protects accumulated knowledge.
|
|
72
|
+
|
|
73
|
+
## Step 2: Gather context
|
|
74
|
+
|
|
75
|
+
Read the folder's `CLAUDE.md` and each `--agent` folder's `CLAUDE.md` and extract:
|
|
76
|
+
|
|
77
|
+
- **Purpose**: what the agent or swarm does, in one paragraph.
|
|
78
|
+
- **Key concepts / domain entities** it reasons about repeatedly.
|
|
79
|
+
- **Recurring source types**: where its inputs come from (digests, reports, emails, articles,
|
|
80
|
+
papers, transcripts).
|
|
81
|
+
- **What the wiki must NOT duplicate**: notebooks or logs it already keeps (a progress file,
|
|
82
|
+
a strategies list, task boards).
|
|
83
|
+
|
|
84
|
+
Infer 4-6 sub-folders for `wiki/` and 2-4 for `raw/`:
|
|
85
|
+
|
|
86
|
+
| Agent kind | wiki/ sub-folders | raw/ sub-folders |
|
|
87
|
+
|---|---|---|
|
|
88
|
+
| trading bot | strategies, indicators, regimes, signals, lessons | digests, reflects, research, market |
|
|
89
|
+
| email reviewer | senders, threads, topics, actions, lessons | inbox-snapshots, rules, research |
|
|
90
|
+
| research agent | sources, topics, entities, syntheses, lessons | papers, articles, transcripts |
|
|
91
|
+
| content creator | formats, audiences, voice, ideas, lessons | drafts, refs, examples |
|
|
92
|
+
|
|
93
|
+
If the domain fits none of these, infer reasonable names from the briefs and go on without
|
|
94
|
+
asking; the schema says this is an initial structure.
|
|
95
|
+
|
|
96
|
+
## Step 3: Create the vault
|
|
97
|
+
|
|
98
|
+
Use hivey's script (in the hivey skill: `~/.claude/skills/hivey/scripts/new_wiki.py`, or
|
|
99
|
+
`~/.agents/skills/hivey/scripts/new_wiki.py` for Codex). It creates `<folder>/<slug>-wiki/` with `raw/`,
|
|
100
|
+
`wiki/`, `index.md`, `log.md`, a starter `CLAUDE.md` and `.obsidian/` (so Obsidian opens it as
|
|
101
|
+
a vault), copies the user's Obsidian look (theme, snippets, Style Settings) from the vault
|
|
102
|
+
remembered in `~/.hivey/wiki.json`, and adds a short "Memory" section to each `--agent`
|
|
103
|
+
folder's `CLAUDE.md`:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
python3 ~/.claude/skills/hivey/scripts/new_wiki.py <slug> --root <folder> \
|
|
107
|
+
--agent <folder or each swarm agent folder> ... --about "<one line: what it does>"
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
It prints JSON with the vault `path`.
|
|
111
|
+
|
|
112
|
+
If the user has a main vault whose look new vaults should copy and none is remembered yet,
|
|
113
|
+
pass `--look-from <that vault>` once (it is remembered).
|
|
114
|
+
|
|
115
|
+
Then add the sub-folders from Step 2:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
mkdir -p <vault>/raw/<sub1> <vault>/raw/<sub2> ... <vault>/wiki/<sub1> <vault>/wiki/<sub2> ...
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Step 4: Write the wiki's CLAUDE.md
|
|
122
|
+
|
|
123
|
+
Replace the starter `<vault>/CLAUDE.md` with the "Wiki CLAUDE.md template" below, filled with
|
|
124
|
+
the context from Step 2. Keep every section (the wiki LLM reads only this file to learn its
|
|
125
|
+
contract): Purpose (concrete, not template wording), Scope rules, Folder structure (the actual
|
|
126
|
+
sub-folders), Ingest workflow, Page format, Citation rules (adapted to the source types),
|
|
127
|
+
Question answering, Lint workflow, Log format, Hard rules.
|
|
128
|
+
|
|
129
|
+
## Step 5: Seed index.md and log.md
|
|
130
|
+
|
|
131
|
+
`<vault>/index.md`: a section header per `wiki/` sub-folder, each empty with a note that pages
|
|
132
|
+
are filed on first ingest. `<vault>/log.md`: a one-line preamble, the log format, and one
|
|
133
|
+
`bootstrap` entry dated today (`date -u +%Y-%m-%d`).
|
|
134
|
+
|
|
135
|
+
## Step 6: Patch the agents' CLAUDE.md
|
|
136
|
+
|
|
137
|
+
The script added a short "Memory" section. Below it, add the "Agent CLAUDE.md section
|
|
138
|
+
template" to the folder's `CLAUDE.md` and each `--agent` folder's `CLAUDE.md`. Write vault
|
|
139
|
+
paths **relative to that file's folder**: `<slug>-wiki/…` for the agent's own folder,
|
|
140
|
+
`../<slug>-wiki/…` for a swarm agent one level down. Never absolute, so the folder still works
|
|
141
|
+
after it's moved or shared.
|
|
142
|
+
|
|
143
|
+
If `~/Obsidian/` exists and has no `<slug>-wiki` yet, also link it there so the user finds it
|
|
144
|
+
next to their other vaults: `ln -s <vault> ~/Obsidian/<slug>-wiki`.
|
|
145
|
+
|
|
146
|
+
## Step 7: Report
|
|
147
|
+
|
|
148
|
+
A short summary: vault path, solo agent or swarm, sub-folders, which `CLAUDE.md` files were patched, how to
|
|
149
|
+
open it ("Obsidian → Open another vault → Open folder as vault → `<vault>`"; on first open,
|
|
150
|
+
"Turn on community plugins" so Style Settings loads, when a look was copied), and how to test:
|
|
151
|
+
`/hivey-wiki-ingest <path-to-source>` from the agent's folder.
|
|
152
|
+
|
|
153
|
+
End with `DONE: created <slug> wiki`.
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Wiki CLAUDE.md template
|
|
158
|
+
|
|
159
|
+
Replace the `{{...}}` placeholders with values from Step 2. Keep all section headings.
|
|
160
|
+
|
|
161
|
+
```markdown
|
|
162
|
+
# LLM Wiki: {{Domain Title}}
|
|
163
|
+
|
|
164
|
+
A persistent, compounding knowledge base for {{the agent / the swarm}}.
|
|
165
|
+
Maintained by its agents following Andrej Karpathy's LLM Wiki pattern.
|
|
166
|
+
|
|
167
|
+
## Purpose
|
|
168
|
+
|
|
169
|
+
{{One paragraph on what this wiki accumulates, from the briefs.}}
|
|
170
|
+
|
|
171
|
+
The wiki accumulates everything learned over time about:
|
|
172
|
+
|
|
173
|
+
{{- bullet list of 4-8 areas, from the key concepts in Step 2}}
|
|
174
|
+
|
|
175
|
+
The wiki is **separate from** {{any notebook/log the agent keeps, named}} and **separate
|
|
176
|
+
from** {{any raw daily input, named}}. Those are sources; the wiki is the synthesis on top.
|
|
177
|
+
|
|
178
|
+
## Scope rules
|
|
179
|
+
|
|
180
|
+
- The wiki is **knowledge / synthesis only**: never live config, runnable code, or current
|
|
181
|
+
operational state. Link to operational state, do not duplicate it.
|
|
182
|
+
- {{Any agent-specific boundary.}}
|
|
183
|
+
|
|
184
|
+
## Folder structure
|
|
185
|
+
|
|
186
|
+
\```
|
|
187
|
+
raw/ -- immutable sources (never modify)
|
|
188
|
+
{{sub-folders chosen in Step 2}}
|
|
189
|
+
wiki/ -- pages maintained by the agents
|
|
190
|
+
{{sub-folders chosen in Step 2}}
|
|
191
|
+
index.md -- catalog of all pages
|
|
192
|
+
log.md -- append-only operations log
|
|
193
|
+
\```
|
|
194
|
+
|
|
195
|
+
Sub-folders are an initial guess. Flatten when a folder has fewer than ~3 pages, split when
|
|
196
|
+
it exceeds ~15. Discuss reorganisations with the user.
|
|
197
|
+
|
|
198
|
+
## Ingest workflow
|
|
199
|
+
|
|
200
|
+
When a new source arrives in `raw/` (or the user asks to ingest something):
|
|
201
|
+
|
|
202
|
+
1. Read the full source.
|
|
203
|
+
2. Discuss key takeaways with the user before writing when they are around; confirm what's
|
|
204
|
+
worth filing.
|
|
205
|
+
3. Create a summary page in the right `wiki/` sub-folder, named after the source
|
|
206
|
+
(lowercase-hyphenated).
|
|
207
|
+
4. Update or create concept pages for each major idea, entity, or topic the source touches.
|
|
208
|
+
**A single source typically touches 10-15 wiki pages; that is normal.**
|
|
209
|
+
5. Add wiki-links (`[[page-name]]`) so every page has inbound and outbound links.
|
|
210
|
+
6. Update `index.md` with new pages and one-line descriptions.
|
|
211
|
+
7. Append an entry to `log.md` (see Log format).
|
|
212
|
+
|
|
213
|
+
## Page format
|
|
214
|
+
|
|
215
|
+
\```markdown
|
|
216
|
+
# Page Title
|
|
217
|
+
|
|
218
|
+
**Summary**: One to two sentences describing this page.
|
|
219
|
+
|
|
220
|
+
**Sources**: List of raw source files this page draws from.
|
|
221
|
+
|
|
222
|
+
**Last updated**: YYYY-MM-DD
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
Main content. Clear headings, short paragraphs. Link related concepts with [[wiki-links]].
|
|
227
|
+
|
|
228
|
+
## Related pages
|
|
229
|
+
|
|
230
|
+
- [[related-concept-1]]
|
|
231
|
+
- [[related-concept-2]]
|
|
232
|
+
\```
|
|
233
|
+
|
|
234
|
+
Use Obsidian callouts when warranted (`> [!warning] Title`); types: `note`, `tip`, `warning`,
|
|
235
|
+
`danger`, `info`, `example`, `quote`.
|
|
236
|
+
|
|
237
|
+
## Citation rules
|
|
238
|
+
|
|
239
|
+
- Every factual / quantitative claim references its source: `(source: filename.pdf p.42)`,
|
|
240
|
+
`(source: 2026-05-11 — title.md)`, or any unambiguous pointer to a file in `raw/`.
|
|
241
|
+
- If two sources disagree, note it in a `> [!warning]` callout and track the open question on
|
|
242
|
+
a `lessons/` (or equivalent) page.
|
|
243
|
+
- A claim without a source is marked `> [!info] Unverified` and flagged at the next lint.
|
|
244
|
+
|
|
245
|
+
## Question answering
|
|
246
|
+
|
|
247
|
+
1. Read `index.md` first to find relevant pages.
|
|
248
|
+
2. Read those pages and synthesize an answer with wiki-page citations.
|
|
249
|
+
3. {{If applicable: also read fresh operational data; never invent numbers.}}
|
|
250
|
+
4. If the answer is not in the wiki, say so.
|
|
251
|
+
5. If the answer is valuable, **offer to file it back as a new wiki page**.
|
|
252
|
+
|
|
253
|
+
## Lint workflow
|
|
254
|
+
|
|
255
|
+
When asked to lint or audit, look for: contradictions between pages, stale claims newer
|
|
256
|
+
sources superseded, orphan pages (no inbound links), concepts in 3+ pages without their own
|
|
257
|
+
page, cross-reference gaps, format compliance (Summary / Sources / Last updated)
|
|
258
|
+
{{, source-coverage gaps if applicable}}. Report a numbered list with suggested fixes; do not
|
|
259
|
+
auto-fix, discuss first.
|
|
260
|
+
|
|
261
|
+
## Log format
|
|
262
|
+
|
|
263
|
+
Every entry in `log.md` starts with a parseable prefix:
|
|
264
|
+
|
|
265
|
+
\```
|
|
266
|
+
## [2026-05-12] ingest | <source name>
|
|
267
|
+
- Created: wiki/<folder>/<page>.md
|
|
268
|
+
- Updated: wiki/<folder>/<page>.md, index.md
|
|
269
|
+
- Notes: <one-line context>
|
|
270
|
+
|
|
271
|
+
## [2026-05-12] query | "<question>"
|
|
272
|
+
- Read: wiki/<folder>/<page>.md, ...
|
|
273
|
+
- Filed answer back as: wiki/<folder>/<new-page>.md (if applicable)
|
|
274
|
+
|
|
275
|
+
## [2026-05-12] lint
|
|
276
|
+
- Findings: N contradictions, M orphan pages, K stale points
|
|
277
|
+
\```
|
|
278
|
+
|
|
279
|
+
`grep "^## \[" log.md | tail -10` gives the last 10 operations.
|
|
280
|
+
|
|
281
|
+
## Hard rules
|
|
282
|
+
|
|
283
|
+
- **Never** modify anything in `raw/`.
|
|
284
|
+
- **Never** put live config, runnable code, or current operational state in the wiki.
|
|
285
|
+
- **Always** update `index.md` and `log.md` after any wiki write.
|
|
286
|
+
- Page filenames: lowercase-hyphenated.
|
|
287
|
+
- {{If applicable: measured data wins over wiki narrative; when they disagree, update the
|
|
288
|
+
wiki.}}
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## Agent CLAUDE.md section template
|
|
294
|
+
|
|
295
|
+
Paths relative to the patched file's folder (`{{vault}}` = `<slug>-wiki` or `../<slug>-wiki`).
|
|
296
|
+
|
|
297
|
+
```markdown
|
|
298
|
+
# {{Slug Title}} wiki: long-term knowledge base
|
|
299
|
+
|
|
300
|
+
You own the Obsidian wiki `{{vault}}/` (an independent vault). Its schema, page format,
|
|
301
|
+
citation rules and workflows are in `{{vault}}/CLAUDE.md`: **always** read it on your first
|
|
302
|
+
wiki touch in a session and follow it exactly.
|
|
303
|
+
|
|
304
|
+
- `{{vault}}/raw/`: immutable sources ({{sub-folders}}). Read-only.
|
|
305
|
+
- `{{vault}}/wiki/`: pages you write ({{sub-folders}}).
|
|
306
|
+
- `{{vault}}/index.md`: table of contents. Read it first when answering.
|
|
307
|
+
- `{{vault}}/log.md`: append-only operations log.
|
|
308
|
+
|
|
309
|
+
Scope: knowledge / synthesis ({{domain examples}}), never live config, runnable code or
|
|
310
|
+
current operational state. Do not duplicate {{named notebook}} or {{named raw input}}.
|
|
311
|
+
|
|
312
|
+
**This wiki is the default place for anything substantive you learn**: research findings,
|
|
313
|
+
summaries of what you read, decisions and their reasons, lessons from successes and failures,
|
|
314
|
+
useful references. Before writing a standalone note or report, ask whether it belongs in the
|
|
315
|
+
wiki instead; durable knowledge almost always does. Exceptions: live state, today's progress,
|
|
316
|
+
ephemeral status.
|
|
317
|
+
|
|
318
|
+
When to touch it:
|
|
319
|
+
1. After every task that produces a finding: create or update the page, update `index.md`,
|
|
320
|
+
add a `log.md` entry. Filing is the default.
|
|
321
|
+
2. When the user adds a source: the Ingest workflow.
|
|
322
|
+
3. When the user asks a question: `index.md` first, answer from the pages, cite them, offer
|
|
323
|
+
to file a valuable answer back.
|
|
324
|
+
4. When asked to lint or audit: the Lint workflow.
|
|
325
|
+
5. When you'd otherwise write a report: write it as a wiki page instead.
|
|
326
|
+
|
|
327
|
+
Hard rules: never modify `{{vault}}/raw/`; no live config or operational state in the wiki;
|
|
328
|
+
always update `index.md` and `log.md` after a wiki write; filenames lowercase-hyphenated.
|
|
329
|
+
```
|