@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,17 @@
1
+ id = "hivey.agent-creator"
2
+ name = "Agent creator"
3
+ version = "0.2.0"
4
+ min_herdr_version = "0.9.0"
5
+ description = "Solo agent setup provider (built in): a Claude designer runs the hivey-agent-creator skill, designs ONE agent with you (on Claude Code, Codex, Grok or agy), writes its brief and wiki, then launches it"
6
+ platforms = ["linux", "macos"]
7
+
8
+ # `hivey swarm new --agent "<task>"` (or `--provider hivey.agent-creator`), run from the folder
9
+ # the agent will live in, opens this pane with HIVEY_SETUP_TASK and HIVEY_SETUP_CWD set. The
10
+ # designer follows the hivey-agent-creator skill (shipped with hivey): asks the user, writes
11
+ # <folder>/CLAUDE.md, makes its wiki with hivey-create-wiki, then `hivey swarm launch <folder>
12
+ # --solo` starts the agent in its own space. This pane stays a designer: close it afterwards.
13
+ [[panes]]
14
+ id = "setup"
15
+ title = "agent setup"
16
+ placement = "tab"
17
+ command = ["sh", "-c", "exec claude --dangerously-skip-permissions --model opus \"/hivey-agent-creator Agent folder: ${HIVEY_SETUP_CWD}\nTask: ${HIVEY_SETUP_TASK}\""]
@@ -0,0 +1,507 @@
1
+ #!/usr/bin/env python3
2
+ """hivey.dashboard: a live terminal dashboard for one hivey swarm.
3
+
4
+ Shows, refreshed every few seconds:
5
+ - budget: elapsed vs. budget_minutes, as a bar
6
+ - agents: role, state (and for how long), model, queued messages, tokens as a bar
7
+ - token rate: a sparkline of the swarm's tokens per interval
8
+ - tasks: counts per status from .swarm/tasks.json (the /swarm skill's task board)
9
+ - recent messages from .swarm/bus.jsonl
10
+
11
+ Tokens are summed from each agent's Claude Code transcripts
12
+ (~/.claude/projects/*/<session>.jsonl and its subagents), deduplicated by message id,
13
+ read incrementally and cached in <root>/.swarm/dashboard_usage.json. Tokens only, no $.
14
+ "Tokens" are new tokens (input + output + cache writes). Cache reads are counted apart: every
15
+ turn re-reads the whole context, so they grow without bound and would drown the real work.
16
+
17
+ Keys: q quit · r refresh now. Environment: HIVEY_SWARM_ROOT (required), HERDR_BIN_PATH.
18
+ """
19
+ import curses
20
+ import glob
21
+ import json
22
+ import os
23
+ import subprocess
24
+ import sys
25
+ import time
26
+ from pathlib import Path
27
+
28
+ PROJECTS = Path.home() / ".claude" / "projects"
29
+ CODEX_SESSIONS = Path.home() / ".codex" / "sessions"
30
+ FIELDS = ("input_tokens", "output_tokens", "cache_creation_input_tokens")
31
+ CACHE_READ = "cache_read_input_tokens"
32
+ CACHE_VERSION = 2 # v1 totals included cache reads; rescan them
33
+ REFRESH_S = 3
34
+ TOKENS_EVERY_S = 10
35
+ SPARK = "▁▂▃▄▅▆▇█"
36
+ GLYPH = {"master": "◆", "worker": "●", "critic": "✎", "script": "▷"}
37
+ TASK_ORDER = ("open", "in-progress", "review", "approved", "blocked")
38
+
39
+
40
+ # ---------------------------------------------------------------------------
41
+ # Pure helpers (unit-tested in test_dashboard.py)
42
+ # ---------------------------------------------------------------------------
43
+
44
+ def human(n):
45
+ return f"{n / 1e6:.1f}M" if n >= 1e6 else f"{n / 1e3:.0f}k" if n >= 1e3 else str(int(n))
46
+
47
+
48
+ def bar(value, maximum, width):
49
+ if width <= 0:
50
+ return ""
51
+ filled = 0 if maximum <= 0 else round(width * min(value, maximum) / maximum)
52
+ return "█" * filled + "░" * (width - filled)
53
+
54
+
55
+ def sparkline(values, width):
56
+ values = list(values)[-width:]
57
+ if not values:
58
+ return ""
59
+ top = max(values) or 1
60
+ return "".join(SPARK[min(len(SPARK) - 1, int(v / top * (len(SPARK) - 1)))] for v in values)
61
+
62
+
63
+ def duration(seconds):
64
+ seconds = int(max(0, seconds))
65
+ if seconds < 60:
66
+ return f"{seconds}s"
67
+ if seconds < 3600:
68
+ return f"{seconds // 60}m"
69
+ return f"{seconds // 3600}h{seconds % 3600 // 60:02d}"
70
+
71
+
72
+ def task_counts(tasks):
73
+ counts = {status: 0 for status in TASK_ORDER}
74
+ for task in tasks:
75
+ status = task.get("status", "open")
76
+ counts[status] = counts.get(status, 0) + 1
77
+ return counts
78
+
79
+
80
+ def scan_transcript(path, state):
81
+ """Add usage from lines appended to `path` since the last scan; returns new tokens.
82
+
83
+ Cache reads go to state["cache_read"]."""
84
+ try:
85
+ with open(path, encoding="utf-8", errors="replace") as f:
86
+ f.seek(state.get("offset", 0))
87
+ while True:
88
+ line = f.readline()
89
+ if not line.endswith("\n"):
90
+ break
91
+ state["offset"] = f.tell()
92
+ if '"usage"' not in line:
93
+ continue
94
+ try:
95
+ msg = json.loads(line).get("message") or {}
96
+ except json.JSONDecodeError:
97
+ continue
98
+ if not isinstance(msg, dict) or not msg.get("usage") or msg.get("id") == state.get("last_id"):
99
+ continue
100
+ state["last_id"] = msg.get("id")
101
+ state["total"] = state.get("total", 0) + sum(int(msg["usage"].get(k) or 0) for k in FIELDS)
102
+ state["cache_read"] = state.get("cache_read", 0) + int(msg["usage"].get(CACHE_READ) or 0)
103
+ except FileNotFoundError:
104
+ pass
105
+ return state.get("total", 0)
106
+
107
+
108
+ def scan_codex_rollout(path, state):
109
+ """Codex rollouts carry a running total in `token_count` events; keep the latest.
110
+
111
+ Codex counts cached input inside input_tokens, so it is moved to state["cache_read"]."""
112
+ try:
113
+ with open(path, encoding="utf-8", errors="replace") as f:
114
+ f.seek(state.get("offset", 0))
115
+ while True:
116
+ line = f.readline()
117
+ if not line.endswith("\n"):
118
+ break
119
+ state["offset"] = f.tell()
120
+ if '"token_count"' not in line:
121
+ continue
122
+ try:
123
+ payload = json.loads(line).get("payload") or {}
124
+ except json.JSONDecodeError:
125
+ continue
126
+ usage = ((payload.get("info") or {}).get("total_token_usage") or {})
127
+ if usage.get("total_tokens") is not None:
128
+ cached = int(usage.get("cached_input_tokens") or 0)
129
+ state["total"] = int(usage["total_tokens"]) - cached
130
+ state["cache_read"] = cached
131
+ except FileNotFoundError:
132
+ pass
133
+ return state.get("total", 0)
134
+
135
+
136
+ def session_files(session):
137
+ """Usage files for one recorded session: "codex:<id>" or a Claude session id."""
138
+ if session.startswith("codex:"):
139
+ sid = session[len("codex:"):]
140
+ return [(p, scan_codex_rollout) for p in glob.glob(str(CODEX_SESSIONS / "*" / "*" / "*" / f"*{sid}.jsonl"))]
141
+ files = glob.glob(str(PROJECTS / "*" / f"{session}.jsonl"))
142
+ files += glob.glob(str(PROJECTS / "*" / session / "subagents" / "*.jsonl"))
143
+ return [(p, scan_transcript) for p in files]
144
+
145
+
146
+ def recent_messages(bus_path, limit):
147
+ try:
148
+ with open(bus_path, "rb") as f:
149
+ f.seek(0, os.SEEK_END)
150
+ f.seek(max(0, f.tell() - 64 * 1024))
151
+ lines = f.read().splitlines()
152
+ except FileNotFoundError:
153
+ return []
154
+ out = []
155
+ for line in lines:
156
+ try:
157
+ record = json.loads(line)
158
+ except json.JSONDecodeError:
159
+ continue
160
+ if record.get("ev") == "msg" and not record.get("copy"):
161
+ out.append(record)
162
+ return out[-limit:]
163
+
164
+
165
+ # ---------------------------------------------------------------------------
166
+ # Data collection
167
+ # ---------------------------------------------------------------------------
168
+
169
+ class Collector:
170
+ def __init__(self, root, binary):
171
+ self.root, self.binary = Path(root), binary
172
+ self.cache_path = self.root / ".swarm" / "dashboard_usage.json"
173
+ try:
174
+ self.cache = json.loads(self.cache_path.read_text())
175
+ except (OSError, json.JSONDecodeError):
176
+ self.cache = {"sessions": {}, "files": {}}
177
+ if self.cache.get("version") != CACHE_VERSION:
178
+ self.cache = {**self.cache, "version": CACHE_VERSION, "files": {}}
179
+ self.since = {} # agent key → (status, first seen at)
180
+ self.rate = [] # swarm tokens gained per token refresh
181
+ self.last_total = None
182
+ self.last_tokens_at = 0
183
+ self.tokens = {}
184
+ self.cache_read = 0
185
+
186
+ def hivey(self, *args):
187
+ out = subprocess.run([self.binary, *args], capture_output=True, text=True)
188
+ try:
189
+ return json.loads(out.stdout)
190
+ except json.JSONDecodeError:
191
+ return {}
192
+
193
+ def swarm(self, slug):
194
+ listing = self.hivey("swarm", "list", "--json")
195
+ return next((s for s in listing.get("swarms", []) if s.get("slug") == slug), None)
196
+
197
+ def refresh_tokens(self, swarm):
198
+ """Map agents to their Claude Code / Codex sessions (by pane), then sum usage."""
199
+ agents = self.hivey("agent", "list").get("result", {}).get("agents", [])
200
+ session_by_pane = {}
201
+ for a in agents:
202
+ session = a.get("agent_session") or {}
203
+ if session.get("value"):
204
+ prefix = "codex:" if session.get("source") == "herdr:codex" else ""
205
+ session_by_pane[a["pane_id"]] = prefix + session["value"]
206
+ for agent in swarm.get("agents", []):
207
+ sid = session_by_pane.get(agent.get("pane_id"))
208
+ known = self.cache["sessions"].setdefault(agent["key"], [])
209
+ if sid and sid not in known:
210
+ known.append(sid)
211
+ tokens, cache_read = {}, 0
212
+ for key, sessions in self.cache["sessions"].items():
213
+ total = 0
214
+ for sid in sessions:
215
+ for path, scan in session_files(sid):
216
+ state = self.cache["files"].setdefault(path, {})
217
+ total += scan(path, state)
218
+ cache_read += state.get("cache_read", 0)
219
+ tokens[key] = total
220
+ tmp = self.cache_path.with_suffix(".tmp")
221
+ tmp.write_text(json.dumps(self.cache))
222
+ tmp.replace(self.cache_path)
223
+ swarm_total = sum(tokens.values())
224
+ if self.last_total is not None:
225
+ self.rate.append(max(0, swarm_total - self.last_total))
226
+ self.rate = self.rate[-120:]
227
+ self.last_total = swarm_total
228
+ self.tokens = tokens
229
+ self.cache_read = cache_read
230
+
231
+ def track_active(self, launched_at, messages, working, now):
232
+ """Seconds the swarm has actually worked: the clock runs only while an agent is working.
233
+
234
+ Kept in the usage cache so it survives restarts. A dashboard started on an existing
235
+ swarm seeds it with launch → last message."""
236
+ if not launched_at:
237
+ return None
238
+ active = self.cache.get("active")
239
+ if active is None:
240
+ last = max((m.get("ts", 0) / 1000 for m in messages), default=launched_at)
241
+ active = self.cache["active"] = {"seconds": max(0, last - launched_at), "at": now}
242
+ if working:
243
+ # Count the time since the last refresh, but not a long gap (dashboard was closed).
244
+ active["seconds"] += min(max(0, now - active["at"]), REFRESH_S * 3)
245
+ active["at"] = now
246
+ return active["seconds"]
247
+
248
+ def snapshot(self, slug, force_tokens=False):
249
+ swarm = self.swarm(slug)
250
+ if swarm is None:
251
+ return None
252
+ now = time.time()
253
+ if force_tokens or now - self.last_tokens_at >= TOKENS_EVERY_S:
254
+ self.refresh_tokens(swarm)
255
+ self.last_tokens_at = now
256
+ for agent in swarm.get("agents", []):
257
+ status = agent.get("status")
258
+ if self.since.get(agent["key"], (None,))[0] != status:
259
+ self.since[agent["key"]] = (status, now)
260
+ manifest = {}
261
+ try:
262
+ manifest = json.loads((self.root / ".swarm" / "agents.json").read_text())
263
+ except (OSError, json.JSONDecodeError):
264
+ pass
265
+ tasks = []
266
+ try:
267
+ tasks = json.loads((self.root / ".swarm" / "tasks.json").read_text()).get("tasks", [])
268
+ except (OSError, json.JSONDecodeError):
269
+ pass
270
+ messages = recent_messages(self.root / ".swarm" / "bus.jsonl", 12)
271
+ working = any(a.get("status") == "working" for a in swarm.get("agents", [])
272
+ if a.get("role") != "script")
273
+ active = self.track_active(manifest.get("launched_at"), messages, working, now)
274
+ return {
275
+ "swarm": swarm,
276
+ "manifest": manifest,
277
+ "tasks": tasks,
278
+ "messages": messages,
279
+ "active": active,
280
+ "working": working,
281
+ "done": bool(tasks) and all(t.get("status") == "approved" for t in tasks),
282
+ "tokens": dict(self.tokens),
283
+ "cache_read": self.cache_read,
284
+ "rate": list(self.rate),
285
+ "since": dict(self.since),
286
+ "now": now,
287
+ }
288
+
289
+
290
+ # ---------------------------------------------------------------------------
291
+ # Rendering
292
+ # ---------------------------------------------------------------------------
293
+
294
+ STATE_COLOR = {"working": 3, "idle": 7, "done": 2, "blocked": 1, "gone": 8, "unknown": 7, "script": 8}
295
+ ROLE_COLOR = {"master": 4, "worker": 5, "critic": 6, "script": 8}
296
+
297
+
298
+ def init_colors():
299
+ curses.start_color()
300
+ curses.use_default_colors()
301
+ pairs = {1: curses.COLOR_RED, 2: curses.COLOR_GREEN, 3: curses.COLOR_CYAN, 4: curses.COLOR_YELLOW,
302
+ 5: curses.COLOR_BLUE, 6: curses.COLOR_MAGENTA, 7: curses.COLOR_WHITE, 8: curses.COLOR_BLACK}
303
+ for pair, color in pairs.items():
304
+ curses.init_pair(pair, color, -1)
305
+
306
+
307
+ def put(win, y, x, text, attr=0):
308
+ height, width = win.getmaxyx()
309
+ if y >= height or x >= width:
310
+ return x
311
+ text = text[: max(0, width - x - 1)]
312
+ try:
313
+ win.addstr(y, x, text, attr)
314
+ except curses.error:
315
+ pass
316
+ return x + len(text)
317
+
318
+
319
+ def color(pair, bold=False):
320
+ attr = curses.color_pair(pair)
321
+ if pair == 8:
322
+ attr |= curses.A_DIM
323
+ return attr | (curses.A_BOLD if bold else 0)
324
+
325
+
326
+ def draw(win, snap, slug):
327
+ win.erase()
328
+ height, width = win.getmaxyx()
329
+ if snap is None:
330
+ put(win, 0, 1, f"swarm {slug!r} not found (hivey swarm list)", color(1))
331
+ win.refresh()
332
+ return
333
+ swarm, manifest, tokens = snap["swarm"], snap["manifest"], snap["tokens"]
334
+ agents = swarm.get("agents", [])
335
+ total = sum(tokens.values())
336
+ if height < len([a for a in agents if a.get("role") != "script"]) + 4:
337
+ draw_compact(win, snap, slug)
338
+ return
339
+ y = 0
340
+
341
+ # Header: swarm, agent count, budget bar, total tokens.
342
+ x = put(win, y, 1, f"◆ {slug}", color(4, True))
343
+ x = put(win, y, x, f" {sum(1 for a in agents if a.get('role') != 'script')} agents", color(7))
344
+ timing = clock(snap)
345
+ if timing:
346
+ label, active, pct = timing
347
+ if pct is None:
348
+ x = put(win, y, x, f" {label}", color(7))
349
+ else:
350
+ budget = manifest["budget_minutes"]
351
+ x = put(win, y, x, f" {label}/{budget}m ", color(7))
352
+ x = put(win, y, x, bar(active, budget * 60, 12), color(budget_pair(pct)))
353
+ x = put(win, y, x, f" {int(pct * 100)}%", color(7))
354
+ put(win, y, max(x + 2, width - 32), f"tokens {human(total):>7}", color(3, True))
355
+ put(win, y, max(x + 18, width - 17), f"cache read {human(snap.get('cache_read', 0)):>5}", color(8))
356
+ y += 2
357
+
358
+ # Agents table with token bars.
359
+ put(win, y, 1, "AGENT STATE MODEL ✉ TOKENS", color(8, True))
360
+ y += 1
361
+ top = max(tokens.values(), default=0)
362
+ bar_width = max(3, width - 51 - 9) # leave room for the number after the bar
363
+ for agent in agents:
364
+ if y >= height - 1:
365
+ break
366
+ if agent.get("role") == "script":
367
+ continue # addons have their own panes and use no tokens
368
+ key, role = agent.get("key", "?"), agent.get("role", "worker")
369
+ status = agent.get("status", "?")
370
+ seen = snap["since"].get(key, (status, snap["now"]))[1]
371
+ x = put(win, y, 1, f"{GLYPH.get(role, '●')} ", color(ROLE_COLOR.get(role, 7), True))
372
+ put(win, y, x, f"{key[:16]:<16}", color(ROLE_COLOR.get(role, 7), role == "master"))
373
+ state_text = status if role == "script" else f"{status} {duration(snap['now'] - seen)}"
374
+ put(win, y, 21, f"{state_text:<16}", color(STATE_COLOR.get(status, 7), status == "blocked"))
375
+ put(win, y, 38, f"{(agent.get('model') or agent.get('kind') or '')[:8]:<8}", color(7))
376
+ queued = agent.get("queued", 0)
377
+ put(win, y, 47, f"{queued if queued else '':>2}", color(4, True))
378
+ if role != "script":
379
+ used = tokens.get(key, 0)
380
+ x = put(win, y, 51, bar(used, top, bar_width), color(ROLE_COLOR.get(role, 7)))
381
+ put(win, y, x + 1, human(used), color(7))
382
+ y += 1
383
+
384
+ # Token rate sparkline.
385
+ y += 1
386
+ put(win, y, 1, "TOKENS / 10s ", color(8, True))
387
+ put(win, y, 14, sparkline(snap["rate"], max(10, width - 30)), color(3))
388
+ if snap["rate"]:
389
+ put(win, y, width - 14, f"last {human(snap['rate'][-1]):>6}", color(7))
390
+ y += 2
391
+
392
+ # Task board summary.
393
+ if snap["tasks"]:
394
+ counts = task_counts(snap["tasks"])
395
+ done = counts.get("approved", 0)
396
+ x = put(win, y, 1, "TASKS ", color(8, True))
397
+ x = put(win, y, x, bar(done, len(snap["tasks"]), 16), color(2))
398
+ x = put(win, y, x, f" {done}/{len(snap['tasks'])} approved ", color(7))
399
+ for status in TASK_ORDER[:-1] + ("blocked",):
400
+ if status == "approved":
401
+ continue
402
+ n = counts.get(status, 0)
403
+ x = put(win, y, x, f"{status} {n} ", color(1 if status == "blocked" and n else 7))
404
+ y += 2
405
+
406
+ # Recent messages.
407
+ put(win, y, 1, "MESSAGES", color(8, True))
408
+ y += 1
409
+ for msg in snap["messages"][-(height - y - 1):]:
410
+ if y >= height - 1:
411
+ break
412
+ when = time.strftime("%H:%M", time.localtime(msg.get("ts", 0) / 1000))
413
+ frm = msg.get("from", "?").split("/")[-1]
414
+ kind = {"fyi": " fyi", "urgent": " URGENT"}.get(msg.get("kind"), "")
415
+ x = put(win, y, 1, f"{when} ", color(8))
416
+ x = put(win, y, x, f"{frm} → {msg.get('to', '?')}{kind}: ", color(4 if kind == " URGENT" else 3))
417
+ put(win, y, x, msg.get("text", "").replace("\n", " "), color(7))
418
+ y += 1
419
+ put(win, height - 1, 1, "q quit · r refresh", color(8))
420
+ win.refresh()
421
+
422
+
423
+ def clock(snap):
424
+ """(label, active seconds, budget fraction or None): time counts only while agents work."""
425
+ active, budget = snap.get("active"), snap["manifest"].get("budget_minutes")
426
+ if active is None:
427
+ return None
428
+ if snap.get("done") and not snap.get("working"):
429
+ label = f"done in {duration(active)}"
430
+ elif snap.get("working"):
431
+ label = f"active {duration(active)}"
432
+ else:
433
+ label = f"idle · active {duration(active)}"
434
+ return label, active, (active / (budget * 60) if budget else None)
435
+
436
+
437
+ def budget_pair(pct):
438
+ return 1 if pct >= 1 else 4 if pct >= 0.8 else 2
439
+
440
+
441
+ def compact_parts(snap, slug):
442
+ """Short-pane summary as (text, color pair, bold) parts: swarm, budget, tokens per agent, total."""
443
+ manifest, tokens = snap["manifest"], snap["tokens"]
444
+ parts = [(f"◆ {slug}", 4, True)]
445
+ timing = clock(snap)
446
+ if timing:
447
+ label, _, pct = timing
448
+ if pct is None:
449
+ parts.append((f" {label}", 7, False))
450
+ else:
451
+ parts.append((f" {label}/{manifest['budget_minutes']}m {int(pct * 100)}%",
452
+ 7 if snap.get("done") else budget_pair(pct), False))
453
+ parts.append((" │", 8, False))
454
+ for agent in snap["swarm"].get("agents", []):
455
+ role = agent.get("role", "worker")
456
+ if role == "script":
457
+ continue
458
+ parts.append((f" {GLYPH.get(role, '●')} {agent.get('key', '?')} ", ROLE_COLOR.get(role, 7), role == "master"))
459
+ parts.append((human(tokens.get(agent.get("key"), 0)), 7, False))
460
+ parts.append((" │ tokens ", 8, False))
461
+ parts.append((human(sum(tokens.values())), 3, True))
462
+ return parts
463
+
464
+
465
+ def draw_compact(win, snap, slug):
466
+ """One or two rows: everything that matters, tokens per agent included."""
467
+ height, width = win.getmaxyx()
468
+ y, x = 0, 1
469
+ for text, pair, bold in compact_parts(snap, slug):
470
+ if x + len(text) >= width - 1 and y + 1 < height and x > 1:
471
+ y, x = y + 1, 3 # wrap onto the next row when there is one
472
+ x = put(win, y, x, text, color(pair, bold))
473
+ win.refresh()
474
+
475
+
476
+ def run(stdscr, collector, slug):
477
+ curses.curs_set(0)
478
+ init_colors()
479
+ stdscr.timeout(REFRESH_S * 1000)
480
+ force = True
481
+ while True:
482
+ try:
483
+ snap = collector.snapshot(slug, force_tokens=force)
484
+ except Exception as err: # keep the dashboard alive through transient errors
485
+ snap = None
486
+ put(stdscr, 0, 1, f"error: {err}")
487
+ force = False
488
+ draw(stdscr, snap, slug)
489
+ key = stdscr.getch()
490
+ if key in (ord("q"), ord("Q")):
491
+ return
492
+ if key in (ord("r"), ord("R")):
493
+ force = True
494
+
495
+
496
+ def main():
497
+ root = os.environ.get("HIVEY_SWARM_ROOT") or (sys.argv[1] if len(sys.argv) > 1 else "")
498
+ if not root:
499
+ sys.exit("HIVEY_SWARM_ROOT is not set (open this through `hivey swarm addon <swarm> hivey.dashboard`)")
500
+ manifest = json.loads((Path(root) / ".swarm" / "agents.json").read_text())
501
+ slug = os.environ.get("HIVEY_SWARM_SLUG") or manifest["slug"]
502
+ collector = Collector(root, os.environ.get("HERDR_BIN_PATH", "hivey"))
503
+ curses.wrapper(run, collector, slug)
504
+
505
+
506
+ if __name__ == "__main__":
507
+ main()
@@ -0,0 +1,14 @@
1
+ id = "hivey.dashboard"
2
+ name = "Swarm dashboard"
3
+ version = "0.1.0"
4
+ min_herdr_version = "0.9.0"
5
+ description = "hivey swarm addon: live pane with agent states, token usage charts, tasks, budget and messages"
6
+ platforms = ["linux", "macos"]
7
+
8
+ # Opened by `hivey swarm launch --addon hivey.dashboard` (or `hivey swarm addon <swarm>
9
+ # hivey.dashboard`) in the swarm's space with HIVEY_SWARM_ROOT / HIVEY_SWARM_SLUG set.
10
+ [[panes]]
11
+ id = "dashboard"
12
+ title = "swarm dashboard"
13
+ placement = "split"
14
+ command = ["sh", "-c", "exec python3 \"$HERDR_PLUGIN_ROOT/dashboard.py\""]
@@ -0,0 +1,134 @@
1
+ """Tests for the hivey dashboard: python3 -m unittest plugins/dashboard/test_dashboard.py"""
2
+ import json
3
+ import sys
4
+ import tempfile
5
+ import unittest
6
+ from pathlib import Path
7
+
8
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
9
+ import dashboard # noqa: E402
10
+
11
+
12
+ class Helpers(unittest.TestCase):
13
+ def test_human_and_bar_and_sparkline(self):
14
+ self.assertEqual([dashboard.human(n) for n in (12, 4200, 3_400_000)], ["12", "4k", "3.4M"])
15
+ self.assertEqual(dashboard.bar(5, 10, 4), "██░░")
16
+ self.assertEqual(dashboard.bar(0, 0, 3), "░░░")
17
+ self.assertEqual(dashboard.bar(99, 10, 2), "██")
18
+ self.assertEqual(dashboard.sparkline([0, 7, 14], 10), "▁▄█")
19
+ self.assertEqual(dashboard.sparkline([], 10), "")
20
+
21
+ def test_duration_and_task_counts(self):
22
+ self.assertEqual([dashboard.duration(s) for s in (5, 125, 3725)], ["5s", "2m", "1h02"])
23
+ counts = dashboard.task_counts([{"status": "open"}, {"status": "approved"}, {}])
24
+ self.assertEqual((counts["open"], counts["approved"], counts["blocked"]), (2, 1, 0))
25
+
26
+
27
+ class Transcripts(unittest.TestCase):
28
+ def test_usage_is_summed_incrementally_and_deduplicated_by_message_id(self):
29
+ with tempfile.TemporaryDirectory() as tmp:
30
+ path = Path(tmp) / "s.jsonl"
31
+
32
+ def line(mid, out):
33
+ usage = {"input_tokens": 10, "output_tokens": out, "cache_read_input_tokens": 100}
34
+ return json.dumps({"message": {"id": mid, "usage": usage}}) + "\n"
35
+
36
+ # Claude Code logs one line per streamed block, all with the same usage.
37
+ path.write_text(line("a", 5) + line("a", 5) + '{"type": "user"}\n')
38
+ state = {}
39
+ # Cache reads are kept apart from the new tokens.
40
+ self.assertEqual(dashboard.scan_transcript(str(path), state), 15)
41
+ self.assertEqual(state["cache_read"], 100)
42
+ with open(path, "a") as f:
43
+ f.write(line("b", 20))
44
+ f.write('{"message": {"id": "c", "usa') # still being written
45
+ self.assertEqual(dashboard.scan_transcript(str(path), state), 15 + 30)
46
+ self.assertEqual(state["cache_read"], 200)
47
+ self.assertEqual(dashboard.scan_transcript(str(path) + ".missing", {}), 0)
48
+
49
+ def test_codex_rollout_keeps_the_latest_running_total(self):
50
+ with tempfile.TemporaryDirectory() as tmp:
51
+ path = Path(tmp) / "rollout-x.jsonl"
52
+
53
+ def event(total, cached=0):
54
+ info = {"total_token_usage": {"total_tokens": total, "cached_input_tokens": cached}}
55
+ return json.dumps({"type": "event_msg", "payload": {"type": "token_count", "info": info}}) + "\n"
56
+
57
+ path.write_text('{"type": "session_meta", "payload": {}}\n' + event(100) + event(250))
58
+ state = {}
59
+ self.assertEqual(dashboard.scan_codex_rollout(str(path), state), 250)
60
+ with open(path, "a") as f:
61
+ f.write(event(400, cached=300))
62
+ self.assertEqual(dashboard.scan_codex_rollout(str(path), state), 100)
63
+ self.assertEqual(state["cache_read"], 300)
64
+
65
+ def test_old_usage_cache_is_rescanned(self):
66
+ with tempfile.TemporaryDirectory() as tmp:
67
+ swarm = Path(tmp) / ".swarm"
68
+ swarm.mkdir()
69
+ old = {"sessions": {"scout": ["s1"]}, "files": {"/x.jsonl": {"offset": 9, "total": 999}}}
70
+ (swarm / "dashboard_usage.json").write_text(json.dumps(old))
71
+ cache = dashboard.Collector(tmp, "hivey").cache
72
+ self.assertEqual((cache["sessions"], cache["files"]), ({"scout": ["s1"]}, {}))
73
+
74
+ def test_recent_messages_skip_receipts_and_copies(self):
75
+ with tempfile.TemporaryDirectory() as tmp:
76
+ bus = Path(tmp) / "bus.jsonl"
77
+ records = [
78
+ {"ev": "msg", "id": "1", "text": "a"},
79
+ {"ev": "delivered", "id": "1"},
80
+ {"ev": "msg", "id": "2", "text": "b", "copy": True},
81
+ {"ev": "msg", "id": "3", "text": "c"},
82
+ ]
83
+ bus.write_text("\n".join(json.dumps(r) for r in records) + "\n{torn")
84
+ self.assertEqual([m["id"] for m in dashboard.recent_messages(bus, 10)], ["1", "3"])
85
+ self.assertEqual(dashboard.recent_messages(Path(tmp) / "none", 5), [])
86
+
87
+
88
+ class Compact(unittest.TestCase):
89
+ def test_short_pane_shows_tokens_per_agent_without_scripts(self):
90
+ snap = {
91
+ "swarm": {"agents": [
92
+ {"key": "coordinator", "role": "master"},
93
+ {"key": "scout", "role": "worker"},
94
+ {"key": "dashboard", "role": "script"},
95
+ ]},
96
+ "manifest": {"launched_at": 1000, "budget_minutes": 60},
97
+ "tokens": {"coordinator": 2_800_000, "scout": 1_900_000, "dashboard": 0},
98
+ "now": 1000 + 5400,
99
+ "active": 540,
100
+ "working": True,
101
+ }
102
+ line = "".join(text for text, _, _ in dashboard.compact_parts(snap, "news"))
103
+ self.assertIn("coordinator 2.8M", line)
104
+ self.assertIn("scout 1.9M", line)
105
+ self.assertIn("active 9m/60m 15%", line)
106
+ self.assertIn("tokens 4.7M", line)
107
+ self.assertNotIn("dashboard", line)
108
+ snap.update(working=False, done=True)
109
+ self.assertEqual(dashboard.clock(snap)[0], "done in 9m")
110
+
111
+
112
+ class ActiveTime(unittest.TestCase):
113
+ def collector(self):
114
+ c = dashboard.Collector.__new__(dashboard.Collector)
115
+ c.cache = {"sessions": {}, "files": {}}
116
+ return c
117
+
118
+ def test_clock_runs_only_while_an_agent_works(self):
119
+ c = self.collector()
120
+ self.assertEqual(c.track_active(1000, [], True, 1000), 0)
121
+ self.assertEqual(c.track_active(1000, [], True, 1003), 3)
122
+ self.assertEqual(c.track_active(1000, [], False, 1500), 3) # idle: frozen
123
+ self.assertEqual(c.track_active(1000, [], True, 1503), 6)
124
+ # A long gap (dashboard closed) adds at most a few refreshes.
125
+ self.assertEqual(c.track_active(1000, [], True, 9000), 6 + dashboard.REFRESH_S * 3)
126
+
127
+ def test_an_existing_swarm_is_seeded_with_launch_to_last_message(self):
128
+ c = self.collector()
129
+ msgs = [{"ts": 1_000_000 + 360_000}] # last message 6 min after launch
130
+ self.assertEqual(c.track_active(1000, msgs, False, 9999), 360)
131
+
132
+
133
+ if __name__ == "__main__":
134
+ unittest.main()