@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
package/repo/README.md ADDED
@@ -0,0 +1,148 @@
1
+ <p align="center">
2
+ <img src="assets/hivey-h.svg" alt="Hivey H logo" width="100" />
3
+ </p>
4
+
5
+ # Hivey
6
+
7
+ ## All your AI swarms. One terminal.
8
+
9
+ **Give Hivey the goal. Let it get the team together.**
10
+
11
+ Hivey is a terminal workspace and coordinating agent for swarms of AI agents. Talk to Hivey to create and manage your swarms. Each swarm has its own workspace and a dedicated coordinator that directs its agents, keeps the work moving, and reports back to you.
12
+
13
+ Run teams with **Claude Code and Codex**, exchange findings across swarms, and stay in touch through **Slack**. Keep reusable knowledge in **Obsidian**, extend the workspace with plugins, and share useful setups through **Skylls**.
14
+
15
+ [Website](https://hivey.dev) · [Install](#install) · [User guide](docs/hivey-guide.md) · [Watch the introduction](#meet-hivey)
16
+
17
+ ### Meet Hivey
18
+
19
+ https://github.com/user-attachments/assets/2091568c-07b5-41f2-810c-9c0834372812
20
+
21
+ *Meet the little H behind your team. This is a stylized character introduction, not a recording of the terminal.*
22
+
23
+ ## How it works
24
+
25
+ 1. **Tell Hivey what you want to do.** Hivey creates a swarm or works with one you already have.
26
+ 2. **Let the coordinator lead.** Each swarm's coordinator assigns work to its agents in a separate terminal space.
27
+ 3. **Keep teams connected.** Agents message teammates; Hivey and coordinators carry findings and requests across swarms.
28
+ 4. **Stay close or step away.** Talk in the terminal or Slack. Detach and return later while agents keep running on your awake, connected machine.
29
+
30
+ You do not need to prompt every swarm yourself. When you want more detail, talk directly to a swarm's coordinator.
31
+
32
+ ## Your tools, working together
33
+
34
+ | Tool or capability | What it adds |
35
+ | --- | --- |
36
+ | Claude Code + Codex | Agent support for teams with different roles. |
37
+ | Swarm messaging | Address agents, roles, or a whole swarm, with queued delivery, inboxes, and message history. Coordinators handle communication across swarms. |
38
+ | Slack | Once connected, talk to Hivey in its channel and to each swarm's coordinator in that swarm's channel. |
39
+ | Scheduled check-ins | Wake an idle coordinator at configured times. |
40
+ | Obsidian memory | Optionally give a swarm a local Markdown wiki for sources, findings, decisions, and reusable knowledge. Open its vault in Obsidian. |
41
+ | Skills + plugins | Extend swarm creation, agent setup, dashboards, integrations, and repeatable workflows. |
42
+ | EnvSave | Configure integrations such as the Slack relay to retrieve credentials with an external `envsave` command. |
43
+ | Skylls | With the separate Skylls tool installed and configured, share and import skills, agents, and whole swarm setups. |
44
+ | Hivey pet + voice | An optional macOS companion that reacts to agent activity and can speak updates aloud. |
45
+ | Quiet mode | One switch, or a daily schedule, that silences voice, sounds and Slack posts while agents keep working. See [Quiet nights](#quiet-nights-quiet-mode-and-quiet-hours). |
46
+ | herdr runtime | The terminal foundation for panes, sessions, and agent workspaces. |
47
+
48
+ ### Quiet nights: quiet mode and quiet hours
49
+
50
+ Swarms can keep working while you sleep without waking you up.
51
+
52
+ **Quiet mode** is one switch for everything. Open the hivey menu (bottom right) and click **quiet mode off** to turn it on, or run `hivey quiet on`. While it is on:
53
+
54
+ - the pet and agents' spoken summaries stay silent (speech bubbles still show)
55
+ - hivey plays no notification sounds or terminal bell
56
+ - Slack posts are held, and when you turn it off they arrive as one catch-up message
57
+ - agents keep working, and anything you write in Slack still reaches them
58
+
59
+ Turn it off the same way, or with `hivey quiet off`.
60
+
61
+ **Quiet mode on a schedule:** so you don't have to press it every night, open **settings → quiet**, click **on**, and set when it starts and ends: click **−** / **+** to move a time by 30 minutes, or select its row and type it (`2230`, `22:30` or `7`). Quiet mode then turns on and off by itself every day, even with every hivey window closed. You can still switch it by hand; your choice lasts until the next start or end. From a terminal: `hivey quiet schedule 22:30-6:45` (`hivey quiet schedule off` to stop).
62
+
63
+ **Voice quiet hours** silence only the voice at the same hours every night, for example from 22:00 to 08:00:
64
+
65
+ ```bash
66
+ hivey voice quiet 22-8 # turn off with: hivey voice quiet off
67
+ ```
68
+
69
+ ### Memory that outlives a chat
70
+
71
+ Swarms can maintain a wiki you can open in Obsidian: original sources, linked knowledge, decisions, and lessons that inform the next task. The approach is inspired by [Karpathy's LLM Wiki as agent memory](https://aaif.io/blog/karpathys-llm-wiki-as-agent-memory). Memory lives in files you and your agents can inspect and maintain.
72
+
73
+ ### Share a team with Skylls
74
+
75
+ Hivey integrates with **[Skylls](https://skylls.dev/)**, a separate website and tool for sharing skills, agents, and complete swarm setups. Share a setup with friends, let their agents reuse it, or import a team someone has shared with you and adapt it to your own work. Recipients configure their own credentials and agent access.
76
+
77
+ ### On the roadmap
78
+
79
+ **Native per-swarm whiteboards** are planned: a shared view for tasks, notes, and decisions. They are not included as a shipped feature here.
80
+
81
+ ## Install
82
+
83
+ **With npm** (prebuilt for Apple Silicon Macs; no Rust or Zig needed):
84
+
85
+ ```bash
86
+ npm install -g @hivey/cli
87
+ hivey setup # skills, hooks, bundled plugins and the lead agent (macOS or Linux, needs Python 3)
88
+ ```
89
+
90
+ `hivey update` then updates through npm. To change Hivey itself, install from source instead.
91
+
92
+ **From source** on **macOS or Linux**.
93
+
94
+ Before starting, install **Git, Rust/Cargo, Zig 0.16.0, and Python 3**. Install **Node.js/npx** for the installer’s skill-library setup. The Hivey lead-agent setup uses Claude Code; configure your chosen agents and their access separately. See [`install.sh`](install.sh) for the current requirements and setup options.
95
+
96
+ ```bash
97
+ git clone https://github.com/alyssaaa11/hivey.git ~/hivey
98
+ cd ~/hivey
99
+ ./install.sh
100
+ ```
101
+
102
+ The installer builds Hivey, links bundled plugins, installs its skill, and walks you through the lead agent and optional integrations. To skip the interactive setup, use `./install.sh --no-setup`.
103
+
104
+ The default install location is `~/.local/bin/hivey`. If your shell cannot find `hivey`, add `~/.local/bin` to your PATH as the installer explains.
105
+
106
+ Start Hivey where your work lives:
107
+
108
+ ```bash
109
+ hivey
110
+ ```
111
+
112
+ Talk to Hivey to get a team started, or create a swarm from the command line:
113
+
114
+ ```bash
115
+ hivey swarm new "Research and build my next idea"
116
+ ```
117
+
118
+ `⌥Q` (or `ctrl+b`, then `q`) detaches. Run `hivey` to reattach. Detaching does not stop the agents, but your machine must stay awake and connected; Hivey is not a hosted service that continues after your computer sleeps.
119
+
120
+ Continue with the **[user guide](docs/hivey-guide.md)** for setup and everyday use.
121
+
122
+ ## Explore the project
123
+
124
+ - [User guide](docs/hivey-guide.md)
125
+ - [Architecture](docs/diagrams/hivey-architecture.html)
126
+ - [New swarm flow](docs/diagrams/hivey-new-swarm.html)
127
+ - [Write a provider](docs/hivey-providers.md)
128
+ - [What hivey installs](docs/hivey-installed.md) — or run `hivey installed`
129
+ - [Agent skill](skills/hivey/SKILL.md) — install with `hivey skill install`
130
+ - [Design](docs/hivey-design.md)
131
+
132
+ ## Development
133
+
134
+ ```bash
135
+ cargo build --release
136
+
137
+ just test # unit tests
138
+ just check # formatting, tests, and maintenance checks
139
+ python3 scripts/third_party_licenses.py # regenerate THIRD_PARTY_LICENSES.md after dependency changes
140
+ ```
141
+
142
+ If you are an AI agent working in this repository, read [`HIVEY.md`](HIVEY.md) and [`AGENTS.md`](AGENTS.md) first. Hivey's fork-specific guidance is in `HIVEY.md`.
143
+
144
+ ## Credits and license
145
+
146
+ Hivey is based on [herdr](https://github.com/herdrdev/herdr), Copyright the herdr authors, licensed under the Apache License 2.0. Hivey is not affiliated with or endorsed by the herdr project; “herdr” describes where this code comes from. See [`NOTICE`](NOTICE).
147
+
148
+ Hivey is licensed under the [Apache License 2.0](LICENSE). Third-party components and their licenses are listed in [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md).
@@ -0,0 +1,365 @@
1
+ #!/usr/bin/env bash
2
+ # Install hivey from this checkout.
3
+ #
4
+ # git clone git@github.com:alyssaaa11/hivey.git ~/hivey
5
+ # cd ~/hivey && ./install.sh
6
+ #
7
+ # Builds hivey, installs it as ~/.local/bin/hivey (HIVEY_BIN_DIR to change), offers the coding
8
+ # agents it runs (Claude Code, Codex, Antigravity/Gemini, Grok) and links each one found to hivey,
9
+ # installs the hivey skills, commands and hooks (safety on; hivey safety off) and the global
10
+ # find-skills skill for Claude Code, installs skylls (the skills library) and envsave (secrets)
11
+ # with their skills, links the bundled plugins (dashboard,
12
+ # Slack relay, GitHub, team template, swarm creator, agent creator, skills), turns on the swarm
13
+ # sidebar and Option keys, asks for your Slack bot token and a desktop pet (macOS), and sets up
14
+ # the hivey agent in ~/.hivey/agent (needs Claude Code; Slack channel #hivey when connected). Swarms and agents keep their Obsidian wiki in their own
15
+ # folder (<folder>/<name>-wiki), so there is no Obsidian folder to set up.
16
+ # --no-setup skips the questions and the hivey agent. Run it again any time; later updates are
17
+ # just `hivey update`. --prebuilt <hivey> skips the build and sets up that installed hivey instead
18
+ # (what `hivey setup` runs after `npm install -g @hivey/cli`).
19
+ #
20
+ # Needs: git, Rust (cargo, via https://rustup.rs), Zig 0.16.0 (https://ziglang.org/download,
21
+ # or set ZIG=/path/to/zig), python3, Node.js (npx for skills.sh, npm for envsave). macOS or Linux.
22
+ set -euo pipefail
23
+
24
+ ROOT="$(cd "$(dirname "$0")" && pwd)"
25
+ cd "$ROOT"
26
+ BIN_DIR="${HIVEY_BIN_DIR:-$HOME/.local/bin}"
27
+ BIN="$BIN_DIR/hivey"
28
+ SETUP=1
29
+ PREBUILT=""
30
+ while [ $# -gt 0 ]; do
31
+ case "$1" in
32
+ --no-setup) SETUP=0 ;;
33
+ --prebuilt) PREBUILT="${2:?--prebuilt needs the path of an installed hivey}"; shift ;;
34
+ -h|--help) sed -n '2,22p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
35
+ *) echo "unknown option $1 (./install.sh [--no-setup] [--prebuilt <hivey>])"; exit 2 ;;
36
+ esac
37
+ shift
38
+ done
39
+ if [ -n "$PREBUILT" ]; then
40
+ BIN="$PREBUILT"
41
+ BIN_DIR="$(dirname "$BIN")"
42
+ fi
43
+
44
+ say() { printf '\n== %s\n' "$*"; }
45
+ fail() { printf 'install: %s\n' "$*" >&2; exit 1; }
46
+
47
+ LOG_DIR="${TMPDIR:-/tmp}"; LOG_DIR="${LOG_DIR%/}"
48
+
49
+ # Everything this run puts on the computer is listed as it happens and again at the end.
50
+ CHANGES="$LOG_DIR/hivey-install-changes.$$"
51
+ : > "$CHANGES"
52
+ tilde() { sed "s#$HOME#~#g"; }
53
+ changed() { # <what> <where>: one change, printed now and kept for the summary
54
+ printf ' %-9s %s\n' "$1" "$2" | tilde | tee -a "$CHANGES"
55
+ }
56
+ # Runs a hivey command, shows its output, and keeps the lines that say what it changed:
57
+ # files new / updated / removed, plugins linked, old copies moved, wikis renamed.
58
+ tracked() {
59
+ local out="$LOG_DIR/hivey-install-step.$$" status=0
60
+ "$@" >"$out" 2>&1 || status=$?
61
+ tilde <"$out"
62
+ grep -E '^ +(new|updated|removed) +|^old (copy|hook|plugin) |^plugin .*: linked$|^wiki .*→|^hivey agent brief .*added|^ *(installed|registered) .* (to|at) |written to |^wrote ' "$out" \
63
+ | sed -E 's/^ +//; s/^plugin (.*): linked$/linked plugin \1/' | tilde | sed 's/^/ /' >>"$CHANGES" || true
64
+ rm -f "$out"
65
+ return "$status"
66
+ }
67
+
68
+ # This machine's own additions to AGENTS.md go here (git ignores it; AGENTS.md points to it).
69
+ NEW_EXTRA=0
70
+ [ -n "$PREBUILT" ] || [ -e EXTRA_AGENTS.md ] || { : > EXTRA_AGENTS.md; NEW_EXTRA=1; }
71
+
72
+ if [ -n "$PREBUILT" ]; then
73
+ say "check requirements"
74
+ case "$(uname -s)" in Darwin|Linux) ;; *) fail "hivey setup runs on macOS or Linux only" ;; esac
75
+ command -v python3 >/dev/null || fail "python3 not found"
76
+ NOW=$("$BIN" --version) || fail "$BIN does not run"
77
+ echo "python3, $NOW: ok"
78
+ else
79
+ say "check requirements"
80
+ case "$(uname -s)" in Darwin|Linux) ;; *) fail "hivey installs on macOS or Linux only" ;; esac
81
+ command -v git >/dev/null || fail "git not found"
82
+ command -v python3 >/dev/null || fail "python3 not found"
83
+ command -v cargo >/dev/null || fail "cargo not found: install Rust from https://rustup.rs, then open a new shell"
84
+ ZIG_BIN="${ZIG:-zig}"
85
+ command -v "$ZIG_BIN" >/dev/null || fail "zig not found: hivey needs Zig 0.16.0 (https://ziglang.org/download), or set ZIG=/path/to/zig"
86
+ ZIG_VERSION=$("$ZIG_BIN" version)
87
+ [ "$ZIG_VERSION" = "0.16.0" ] || fail "zig $ZIG_VERSION found, hivey needs Zig 0.16.0 exactly (set ZIG=/path/to/zig-0.16.0)"
88
+ [ -d .git ] || fail "run this from a git clone of hivey (hivey update needs it)"
89
+
90
+ . scripts/ensure-rust-toolchain.sh
91
+ ensure_rust_toolchain || fail "Rust is not ready (see above)"
92
+ echo "git, python3, $(cargo --version), zig $ZIG_VERSION: ok"
93
+
94
+ say "the hivey checkout ($ROOT)"
95
+ [ "$NEW_EXTRA" = 1 ] && changed new "$ROOT/EXTRA_AGENTS.md (this machine's own additions to AGENTS.md; git ignores it)"
96
+ # The upstream remote is only for maintainers (hivey update --check merges herdr); never pushed to.
97
+ if ! git remote get-url upstream >/dev/null 2>&1; then
98
+ git remote add upstream https://github.com/herdrdev/herdr
99
+ git remote set-url --push upstream DISABLED
100
+ changed added "git remote upstream → https://github.com/herdrdev/herdr (fetch only, push disabled)"
101
+ else
102
+ echo " git remotes: as they are"
103
+ fi
104
+
105
+ say "build (the first build takes a few minutes)"
106
+ BUILD_LOG="$LOG_DIR/hivey-install-build.log"
107
+ if ! cargo build --release >"$BUILD_LOG" 2>&1; then
108
+ grep -vE "external contributor policy|^warning: hivey@" "$BUILD_LOG" | grep -E -A5 "^error" | head -30 >&2
109
+ fail "build failed (full log: $BUILD_LOG)"
110
+ fi
111
+ grep -vE "external contributor policy|^warning: hivey@" "$BUILD_LOG" | tail -3
112
+ [ -x target/release/hivey ] || fail "build finished but target/release/hivey is missing"
113
+
114
+ say "the hivey program"
115
+ mkdir -p "$BIN_DIR"
116
+ BEFORE=$("$BIN" --version 2>/dev/null || true)
117
+ # Never cp over an existing binary: macOS then kills every new exec of it (code signature).
118
+ cp target/release/hivey "$BIN.new" && mv -f "$BIN.new" "$BIN"
119
+ NOW=$("$BIN" --version)
120
+ if [ -z "$BEFORE" ]; then
121
+ changed new "$BIN ($NOW)"
122
+ elif [ "$BEFORE" != "$NOW" ]; then
123
+ changed updated "$BIN ($BEFORE → $NOW)"
124
+ else
125
+ echo " $BIN: $NOW (reinstalled)" | tilde
126
+ fi
127
+ mkdir -p "$HOME/.local/state/hivey"
128
+ STATE="$HOME/.local/state/hivey/installed-commit"
129
+ [ -e "$STATE" ] || NEW_STATE=1
130
+ git rev-parse --short HEAD >"$STATE"
131
+ [ "${NEW_STATE:-0}" = 1 ] && changed new "$STATE (which commit is installed)"
132
+ fi
133
+
134
+ say "coding agents hivey runs (Claude Code, Codex, Antigravity/Gemini, Grok)"
135
+ # Each one found is linked to hivey (`hivey integration install`) so its panes show working /
136
+ # idle / blocked. Missing ones are offered (Claude Code by default: the hivey agent and the
137
+ # creators run on it).
138
+ ask_yes() { # question, default (y|n); no terminal: the default without asking
139
+ local answer prompt="[y/N]"
140
+ [ "$2" = y ] && prompt="[Y/n]"
141
+ if [ "$SETUP" = 1 ] && { [ -t 0 ] || (: </dev/tty) 2>/dev/null; }; then
142
+ printf '%s %s ' "$1" "$prompt"
143
+ read -r answer </dev/tty || answer=""
144
+ fi
145
+ case "${answer:-$2}" in [yY]*) return 0 ;; *) return 1 ;; esac
146
+ }
147
+ js_global() { # npm package: installed with bun if present, else npm
148
+ if command -v bun >/dev/null; then bun install -g "$1@latest"
149
+ elif command -v npm >/dev/null; then npm install -g "$1@latest"
150
+ else echo "needs bun or npm (Node.js)"; return 1; fi
151
+ }
152
+ install_claude() { if command -v bun >/dev/null || command -v npm >/dev/null; then js_global @anthropic-ai/claude-code; else curl -fsSL https://claude.ai/install.sh | bash; fi; }
153
+ install_codex() { js_global @openai/codex; }
154
+ install_agy() { curl -fsSL https://antigravity.google/cli/install.sh | bash; }
155
+ install_grok() { curl -fsSL https://x.ai/cli/install.sh | bash; }
156
+ for agent in "claude:Claude Code:claude:y" "codex:Codex:codex:n" "agy:Antigravity (Gemini):antigravity-cli:n" "grok:Grok:grok:n"; do
157
+ IFS=: read -r cmd label target default <<<"$agent"
158
+ [ -x "$HOME/.grok/bin/grok" ] && [ "$cmd" = grok ] && export PATH="$HOME/.grok/bin:$PATH"
159
+ if ! command -v "$cmd" >/dev/null; then
160
+ if ask_yes "$label is not installed. Install it?" "$default"; then
161
+ if "install_$cmd"; then
162
+ hash -r
163
+ command -v "$cmd" >/dev/null && changed installed "$label: $(command -v "$cmd")"
164
+ else
165
+ echo " could not install $label"
166
+ fi
167
+ else
168
+ echo " $label: not installed (later: rerun ./install.sh)"
169
+ continue
170
+ fi
171
+ fi
172
+ command -v "$cmd" >/dev/null || { echo " $label: not found after installing (open a new shell, then rerun ./install.sh)"; continue; }
173
+ echo " $label: $("$cmd" --version 2>/dev/null | head -1)"
174
+ tracked "$BIN" integration install "$target" | sed 's/^/ /' \
175
+ || echo " could not link $label to hivey (later: hivey integration install $target)"
176
+ done
177
+
178
+ say "hivey skills (Claude Code ~/.claude/skills, Codex ~/.agents/skills)"
179
+ if [ -d "$HOME/.claude" ] || [ -d "$HOME/.codex" ]; then
180
+ tracked "$BIN" skill install || echo " could not install everything (later: hivey skill install)"
181
+ else
182
+ echo " no Claude Code or Codex found: skipped (later: hivey skill install)"
183
+ fi
184
+
185
+ # Reinstalls over an older hivey: bring its leftovers to the current conventions too.
186
+ say "hivey hooks, plugins and older leftovers (hivey migrate: safety on)"
187
+ tracked "$BIN" migrate || echo " could not migrate everything (later: hivey migrate)"
188
+
189
+ # find-skills (skills.sh) is the one skill installed globally: creators use it to find skills an
190
+ # agent needs; those skills then go into the agent's own folder, never the global ones.
191
+ say "find-skills (global Claude Code skill)"
192
+ if [ -f "$HOME/.claude/skills/find-skills/SKILL.md" ]; then
193
+ echo "already installed"
194
+ elif ! command -v npx >/dev/null; then
195
+ echo "npx not found (install Node.js): skipped (later: npx -y skills add vercel-labs/skills --skill find-skills -g -a claude-code -y)"
196
+ elif npx -y skills add vercel-labs/skills --skill find-skills -g -a claude-code -y >"$LOG_DIR/hivey-find-skills.log" 2>&1; then
197
+ changed new "$HOME/.claude/skills/find-skills (from skills.sh)"
198
+ else
199
+ echo "could not install (see $LOG_DIR/hivey-find-skills.log; later: npx -y skills add vercel-labs/skills --skill find-skills -g -a claude-code -y)"
200
+ fi
201
+
202
+ # skylls (the skills library creators find, save and share skills, agents and swarms in) and
203
+ # envsave (secrets by opaque id, never in code), each with its global skill. An existing skill
204
+ # is left as it is.
205
+ SKYLLS_URL=https://raw.githubusercontent.com/jcsancho/skylls/main/install.sh
206
+ say "skylls and envsave (tools and their skills)"
207
+ if ! command -v skylls >/dev/null 2>&1; then
208
+ # Its installer asks its own questions on the terminal (uv, gh, gitleaks, your account);
209
+ # --no-setup leaves its account setup for later.
210
+ SKYLLS_OPT=""; [ "$SETUP" = 1 ] || SKYLLS_OPT=--no-setup
211
+ if bash -c "$(curl -fsSL "$SKYLLS_URL")" skylls-install $SKYLLS_OPT; then
212
+ export PATH="$HOME/.local/bin:$PATH"
213
+ hash -r
214
+ fi
215
+ command -v skylls >/dev/null 2>&1 && changed installed "skylls: $(command -v skylls)"
216
+ fi
217
+ if command -v skylls >/dev/null 2>&1; then
218
+ echo " skylls $(skylls --version 2>/dev/null | awk '{print $NF}')"
219
+ if [ -f "$HOME/.claude/skills/skylls/SKILL.md" ]; then
220
+ echo " skylls skill: already installed"
221
+ elif skylls agent-skill -g -a all >"$LOG_DIR/hivey-skylls-skill.log" 2>&1 \
222
+ && [ -f "$HOME/.claude/skills/skylls/SKILL.md" ]; then
223
+ changed new "$HOME/.claude/skills/skylls (skylls agent-skill -g)"
224
+ else
225
+ echo " could not install the skylls skill (see $LOG_DIR/hivey-skylls-skill.log; needs gh auth login and skylls setup; later: skylls agent-skill -g -a all)"
226
+ fi
227
+ else
228
+ echo " skylls: not installed (later: bash -c \"\$(curl -fsSL $SKYLLS_URL)\")"
229
+ fi
230
+ if ! command -v envsave >/dev/null 2>&1; then
231
+ if js_global @envsave/cli; then
232
+ hash -r
233
+ command -v envsave >/dev/null 2>&1 && changed installed "envsave: $(command -v envsave)"
234
+ fi
235
+ fi
236
+ if command -v envsave >/dev/null 2>&1; then
237
+ echo " envsave: $(command -v envsave | tilde)"
238
+ if [ -f "$HOME/.claude/skills/envsave/SKILL.md" ]; then
239
+ echo " envsave skill: already installed"
240
+ elif envsave install-skill --agent claude --global </dev/null >"$LOG_DIR/hivey-envsave-skill.log" 2>&1 \
241
+ && [ -f "$HOME/.claude/skills/envsave/SKILL.md" ]; then
242
+ changed new "$HOME/.claude/skills/envsave (envsave install-skill --global)"
243
+ else
244
+ echo " could not install the envsave skill (see $LOG_DIR/hivey-envsave-skill.log; later: envsave install-skill --global)"
245
+ fi
246
+ [ -f "$HOME/.envsave/vault.enc" ] || echo " no vault yet: envsave activate <license>, then envsave init"
247
+ else
248
+ echo " envsave: not installed (later: npm install -g @envsave/cli; needs Node.js)"
249
+ fi
250
+
251
+ say "bundled plugins"
252
+ STARTED_SERVER=0
253
+ if ! "$BIN" plugin list >/dev/null 2>&1; then
254
+ # Linking talks to a server: start a headless one just for this.
255
+ "$BIN" server >/tmp/hivey-install-server.log 2>&1 &
256
+ STARTED_SERVER=1
257
+ for _ in 1 2 3 4 5 6 7 8 9 10; do
258
+ "$BIN" plugin list >/dev/null 2>&1 && break
259
+ sleep 1
260
+ done
261
+ fi
262
+ LINKED=$("$BIN" plugin list 2>/dev/null || true)
263
+ for manifest in plugins/*/herdr-plugin.toml; do
264
+ dir="$ROOT/$(dirname "$manifest")"
265
+ id=$(sed -n 's/^id *= *"\(.*\)"/\1/p' "$manifest" | head -1)
266
+ if printf '%s' "$LINKED" | grep -q "^- $id "; then
267
+ echo " $id: already installed"
268
+ elif "$BIN" plugin link "$dir" >/dev/null 2>&1; then
269
+ changed linked "plugin $id"
270
+ else
271
+ echo " $id: could not link (try later: hivey plugin link $dir)"
272
+ fi
273
+ done
274
+ # Stopped on exit: the Slack and hivey-agent steps below talk to it too.
275
+ if [ "$STARTED_SERVER" = 1 ]; then trap '"$BIN" server stop >/dev/null 2>&1 || true' EXIT; fi
276
+
277
+ if [ "$SETUP" = 1 ]; then
278
+ say "swarm sidebar and keys"
279
+ tracked "$BIN" swarm setup || true
280
+
281
+ say "Slack (talk to hivey and your agents from Slack; needed for Slack channels)"
282
+ SLACK=0
283
+ if "$BIN" slack status >/dev/null 2>&1; then
284
+ "$BIN" slack status
285
+ SLACK=1
286
+ elif [ -t 0 ] || (: </dev/tty) 2>/dev/null; then
287
+ # Asked on the terminal even when stdin is redirected (e.g. curl … | bash).
288
+ echo "Slack isn't connected on this machine: hivey needs your Slack app's bot token"
289
+ echo "(xoxb-…, typed hidden; the next step shows how to create the app if you have none)."
290
+ printf 'Connect Slack now? [Y/n] '
291
+ read -r answer </dev/tty || answer=n
292
+ case "$answer" in
293
+ [nN]*) echo "skipped (later: hivey slack connect)" ;;
294
+ *) "$BIN" slack connect </dev/tty && SLACK=1 && changed new "$HOME/.hivey/slack.json (the Slack bot token)" ;;
295
+ esac
296
+ else
297
+ echo "skipped: no terminal to type the token in (later: hivey slack connect)"
298
+ fi
299
+
300
+ say "online skill search (skills.sh, for skills skylls lacks)"
301
+ if [ -t 0 ] || (: </dev/tty) 2>/dev/null; then
302
+ printf 'Search skills.sh for skills skylls lacks (asks before installing any)? [Y/n] '
303
+ read -r answer </dev/tty || answer=""
304
+ case "$answer" in
305
+ [nN]*) "$BIN" skills online off && changed set "$HOME/.hivey/skills.json (online skill search off)" ;;
306
+ *) "$BIN" skills online on && changed set "$HOME/.hivey/skills.json (online skill search on)" ;;
307
+ esac
308
+ else
309
+ echo "skipped: no terminal (online search stays on; later: hivey settings → skills)"
310
+ fi
311
+
312
+ say "desktop pet (optional)"
313
+ if [ "$(uname -s)" != Darwin ]; then
314
+ echo "pets are macOS apps: skipped"
315
+ elif [ -t 0 ]; then
316
+ # Builds the chosen pet (about a minute) and starts it; it then shows while hivey is open.
317
+ "$BIN" pet choose || echo "no pet for now (later: hivey pet choose, or ⌥P)"
318
+ else
319
+ echo "skipped: not a terminal (later: hivey pet choose)"
320
+ fi
321
+
322
+ say "the hivey agent (~/.hivey/agent)"
323
+ if command -v claude >/dev/null; then
324
+ # Turned on for the default session; it starts with hivey. With Slack: channel #hivey.
325
+ if [ "$SLACK" = 1 ]; then
326
+ tracked "$BIN" home setup --no-start --slack || {
327
+ echo "could not set up Slack #hivey (later: hivey home setup --slack)"
328
+ tracked "$BIN" home setup --no-start
329
+ }
330
+ else
331
+ tracked "$BIN" home setup --no-start
332
+ echo "Slack #hivey later: hivey slack connect, then hivey home setup --slack"
333
+ fi
334
+ else
335
+ echo "Claude Code not found: skipped (later: hivey home setup)"
336
+ fi
337
+ fi
338
+
339
+ say "what this install changed on this computer"
340
+ if [ -s "$CHANGES" ]; then
341
+ sort -u "$CHANGES"
342
+ else
343
+ echo " nothing: everything was already up to date"
344
+ fi
345
+ rm -f "$CHANGES"
346
+
347
+ say "everything hivey has on this computer (hivey installed)"
348
+ "$BIN" installed | tilde || true
349
+
350
+ say "done"
351
+ case ":$PATH:" in
352
+ *":$BIN_DIR:"*) ;;
353
+ *) echo "Add $BIN_DIR to your PATH, e.g.: echo 'export PATH=\"$BIN_DIR:\$PATH\"' >> ~/.zshrc" ;;
354
+ esac
355
+ cat <<EOF
356
+ Start hivey: hivey
357
+ New swarm: hivey swarm new "<task>" (from the project folder)
358
+ Update later: hivey update
359
+ EOF
360
+ [ -z "$PREBUILT" ] || echo " (an npm install: runs npm install -g @hivey/cli@latest)"
361
+ if [ "$SETUP" = 1 ] && [ "$SLACK" = 0 ]; then
362
+ echo
363
+ echo "Slack is NOT connected: agents can't get Slack channels until you run"
364
+ echo " hivey slack connect (asks for the Slack bot token, then: hivey home setup --slack)"
365
+ fi
@@ -0,0 +1,25 @@
1
+ # hivey pets (macOS)
2
+
3
+ Desktop pets that act out what hivey's agents do. Choose one (or none) with `hivey pet choose`,
4
+ `⌥P`, hivey's menu → pets, or `install.sh`; switch from the pet's right-click menu.
5
+
6
+ | id | name | look |
7
+ |---|---|---|
8
+ | `hivey-h` | Hivey | a 3D H; its sections slide apart to hand out work |
9
+ | `hivey-dot` | Hivey System | a graphite dot; its agents ride a signal wave around it |
10
+ | `hivey-prompt` | Hivey Prompt | a `>_` sphere leading three agent spheres |
11
+
12
+ - `<id>/main.swift` + `<id>/build.sh`: the pet (AppKit + Core Graphics); each `CLAUDE.md` is
13
+ its character spec and behavior, read it before changing a pet.
14
+ - `shared/HiveyWatch.swift`: compiled into every pet. `HiveyWatcher` polls hivey
15
+ (`swarm list` / `msg log`), `HiveySnapshot` turns two looks into `HiveyEvent`s (launched,
16
+ needs you, finished, message), `PetSwitcher` is the Switch pet / Turn off pet menu.
17
+ - `pet.py`: `hivey pet` (build, install to `~/Applications`, switch, off, show). The
18
+ choice is in `~/.hivey/pet.json`; `hivey update` runs `hivey pet refresh` to rebuild it when
19
+ its source changed.
20
+ - Chat: clicking a pet opens `HiveyChat` (a box above it); Enter sends the text to the hivey
21
+ agent (`hivey msg send hivey/master`), whose reply to `human` the pet shows and says
22
+ (`replyLine`). Other agents' replies are announced as "<agent> replied.".
23
+ - Lifecycle: every hivey window writes `~/.hivey/windows/<pid>` while open and runs
24
+ `hivey pet show`, so the pet appears with the first window; the pet quits itself ~6s after the
25
+ last window closes (`HiveyWatcher.onLastWindowClosed`). Pets don't open at login.
@@ -0,0 +1,55 @@
1
+ # Hivey System — desktop pet
2
+
3
+ ## READ FIRST — before running, building, or connecting Hivey to anything
4
+
5
+ 1. Read this whole file. The **Character spec** below is the source of truth for how Hivey looks, moves and behaves; never change its identity without the user asking.
6
+ 2. **Show the user the full "Future capabilities" section** — the event table and every planned building block — before connecting anything. Also tell them what Hivey does **today** (see Behavior) and point them to the demo GIF `docs/capabilities-demo.gif`, which acts out every capability.
7
+ 3. Let the user choose: connect **one** capability, **several**, or **all**. Do not connect Hivey to hooks, swarms, Slack or any external service until they choose — connecting changes what happens on their desktop. If they choose all, build the blocks in the listed order, one at a time, and verify each before starting the next.
8
+ 4. When adding a capability: drive it through the existing animations (`addAgent`, `formSwarm`, `celebrate`, `say`, the pulses between dots) — new behavior must reuse the character's movement vocabulary and stay professional (dark graphite body, mint accents, signal wave, no cheeks, mouth only while speaking). Rebuild with `./build.sh` and verify with a screenshot of the window.
9
+ 5. After a capability ships, move it from "Future capabilities" into "Behavior".
10
+
11
+ ## Character spec
12
+
13
+ Hivey is a small, soft dot with expressive eyes and a calm, curious personality. It represents the main agent—the friendly conductor that creates agents, coordinates swarms, and keeps everyone connected. Its look is professional, in "harness" mode: a dark graphite satin body with glowing mint eyes, no cheeks, and a mouth that appears only while it speaks.
14
+
15
+ Small mint-green dots travel around its body, representing the agents it manages. They ride a delicate glowing **signal wave**—a loop that ripples like a live signal, with a bright packet running along it—giving Hivey a gentle sense of life even while idle.
16
+
17
+ When Hivey creates an agent, a new dot appears on its signal. As it coordinates a swarm, the dots move into formation. When agents exchange messages, tiny pulses of light travel between them. When a task finishes, Hivey gives a small, restrained lift and its companions briefly glow.
18
+
19
+ Its design stays simple and recognizable: one thoughtful little dot, surrounded by a world of teamwork.
20
+
21
+ ## Future capabilities (not built yet)
22
+
23
+ | Capability | Notes |
24
+ |---|---|
25
+ | Claude Code hooks | React to Claude sessions *outside* hivey via hooks in `~/.claude/settings.json` calling the event CLI. Changes every Claude session on the Mac: only with the user's OK. |
26
+ | Slack summary | Slack posts already pulse (they reach the bus from `human`); optionally `say` a short summary. |
27
+
28
+ ## Overview
29
+
30
+ Professional "harness" look: a dark graphite satin sphere (key light upper-left, mint bounce light underneath) with glowing mint-white eyes; small mint dots (its agents) ride a glowing **signal wave** — a tilted loop whose radius carries a travelling sine wave, with a brighter signal packet running along it. Mouth only while speaking, no cheeks. Dark terminal-style speech bubble (monospaced). Watches hivey: its dots are hivey's agents. `main.swift` (AppKit + Core Graphics) plus the shared `../shared/HiveyWatch.swift`. Previous ivory version saved in `backup/main.ivory-orbit.swift`.
31
+
32
+ ## Files
33
+ - `main.swift` — the whole app: Hivey + orbit drawing/animation, speech bubble, `say` voice.
34
+ - `build.sh` — builds universal (arm64 + x86_64, macOS 12+) ad-hoc-signed `Hivey System.app` and `dist/HiveySystem.zip` for sharing. Run after every change.
35
+
36
+ ## Behavior
37
+ - Click = chat box above the pet (`HiveyChat`): Enter sends to the hivey agent (`hivey msg send hivey/master`), Esc / clicking away closes; the agent's reply to `human` is shown in the bubble and said aloud. Drag still moves the pet.
38
+ - Lives in the hivey repo (`pets/hivey-dot/`). Built and installed by `hivey pet use hivey-dot` (into `~/Applications`; the other pets are quit); `./build.sh` compiles `main.swift` with the shared `../shared/HiveyWatch.swift`.
39
+ - Right-click: hivey status line ("hivey: N agents, M working"), Watch hivey, Speak aloud, Effects (preview only) ▸ (plays the pet's moves; nothing happens in hivey), Switch pet ▸ (Hivey / Hivey Prompt / Hivey, via `hivey pet use`), Turn off pet (`hivey pet off`), Quit.
40
+ - Watches hivey through the shared `HiveyWatcher` (every 2s: `hivey swarm list --json` + `hivey msg log --json`, default session, never starts a server, nothing replayed on first look). Spoken aloud: "<slug> is starting.", "<agent> needs you.", "<agent> replied."; "<agent> finished." is bubble-only; one line per look, most urgent first.
41
+ - Debug: `HIVEY_BIN=/path/to/fake-hivey HIVEY_H_DEBUG=1 <app>/Contents/MacOS/<exe>` logs each look's events.
42
+ - hivey → Hivey: dots on the wave = hivey's agents (max 9; `showAgents`: new dots fly out, gone ones fade off via `removeAgent`) · swarm/agent starts → `formSwarm` · agents working → `busy` (frequent pulses) · message → `pulse()` between two dots · message from the user → bubble "On it." · agent finished → `celebrate`.
43
+ - Event CLI: `Hivey.app/Contents/MacOS/hivey agent|leave|swarm|pulse|done ["text"]` (DistributedNotification `com.hivey.pet.event`).
44
+ - On launch: fades in, small restrained lift + mint glow, says "Welcome! I'm Hivey." (bubble + voice). Always visible, floats above windows, on all Spaces.
45
+ - Idle: agents travel the signal wave (`signalPoint`, depth-sorted behind/in front of Hivey), breathing, blinking, eyes follow the cursor, occasional message pulse between agents.
46
+ - Click = small lift + glow, and the chat box opens (see above).
47
+ - Effects (preview only) ▸: New agent (dot flies out, max 9), Swarm formation (dots arc above Hivey, frequent pulses, 5s), Task finished (lift + glow), Quit.
48
+ - A crew-motion variant (no orbit; idle groups, errands, listen/swarm/tidy formations) was tried on 2026-10-02 and rejected — user prefers the orbit.
49
+ - Drag = move (position autosaved as `HiveyPet`).
50
+ - `Hivey.app/Contents/MacOS/hivey say "text"` makes the running pet talk.
51
+ - One instance per Mac.
52
+
53
+ ## Sharing / lifecycle
54
+ - Shows while hivey is open: each hivey window writes `~/.hivey/windows/<pid>` and runs `hivey pet show`; the pet quits itself ~6s after the last live window is gone (`HiveyWatcher.onLastWindowClosed`). No Open at Login: switching removes old `~/Library/LaunchAgents/com.hivey.pet.plist` items.
55
+ - Share it through hivey (`hivey pet use hivey-dot`): ad-hoc signed, built on the user's Mac, so no quarantine prompt.
@@ -0,0 +1,34 @@
1
+ #!/bin/bash
2
+ # Builds "Hivey System.app" (universal: Apple Silicon + Intel) and dist/HiveySystem.zip for sharing
3
+ set -euo pipefail
4
+ cd "$(dirname "$0")"
5
+
6
+ APP="Hivey System.app"
7
+ rm -rf "$APP" dist
8
+ mkdir -p "$APP/Contents/MacOS" dist
9
+
10
+ for arch in arm64 x86_64; do
11
+ swiftc -O -target "$arch-apple-macos12" main.swift ../shared/HiveyWatch.swift -o "/tmp/hivey-$arch"
12
+ done
13
+ lipo -create /tmp/hivey-arm64 /tmp/hivey-x86_64 -output "$APP/Contents/MacOS/hivey"
14
+ rm -f /tmp/hivey-arm64 /tmp/hivey-x86_64
15
+
16
+ cat > "$APP/Contents/Info.plist" <<'EOF'
17
+ <?xml version="1.0" encoding="UTF-8"?>
18
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
19
+ <plist version="1.0">
20
+ <dict>
21
+ <key>CFBundleIdentifier</key><string>com.hivey.pet</string>
22
+ <key>CFBundleName</key><string>Hivey System</string>
23
+ <key>CFBundleExecutable</key><string>hivey</string>
24
+ <key>CFBundlePackageType</key><string>APPL</string>
25
+ <key>CFBundleShortVersionString</key><string>1.0</string>
26
+ <key>LSMinimumSystemVersion</key><string>12.0</string>
27
+ <key>LSUIElement</key><true/>
28
+ </dict>
29
+ </plist>
30
+ EOF
31
+
32
+ codesign --force --deep -s - "$APP"
33
+ ditto -c -k --keepParent "$APP" dist/HiveySystem.zip
34
+ echo "Built $APP and dist/HiveySystem.zip"