Tools
Hawkins
By OpenClaw plugin: durable orchestration state (VINES) + decay-aware shared agent memory (VECNA) for multi-agent swarms. 12 typed tools, MariaDB-backed, optional Linear oversight. Stranger Thingsโthemed. Published on npm + ClawHub.
Install
npm install
makeREADME
<p align="center">
<img src="https://drive.google.com/uc?export=view&id=1NgcqDQd7dUzFsSWdC67oNJVNJREBcdwh" alt="openclaw-hawkins โ The Nexus ยท The Tendrils ยท The Hive โ Everything is Connected" width="100%">
</p>
# ๐ฉธ Openclaw Hawkins โ Multi-Agent Orchestration for OpenClaw
[](https://github.com/parijatmukherjee/openclaw-hawkins/actions/workflows/ci.yml)
[](https://codecov.io/gh/parijatmukherjee/openclaw-hawkins)
[](https://nodejs.org)
[](https://www.typescriptlang.org)
[](https://prettier.io)
[](https://eslint.org)
[](LICENSE)
[](https://github.com/parijatmukherjee/openclaw-hawkins/stargazers)
> **Everything is Connected.**
A multi-agent orchestration pattern โ **demonstrated on [OpenClaw](https://openclaw.ai)** โ where one conversational orchestrator (**the Nexus**) coordinates six isolated specialist agents (**the Tendrils**), with durable state that survives restarts (**VINES**) and decay-aware shared memory (**VECNA**). The brand vocabulary is [Stranger Things](https://www.netflix.com/title/80057281)โcoloured; the protocol is grounded engineering.
> โญ **Find this useful?** Star the repo โ it surfaces the pattern to other OpenClaw operators and tells me whether to keep iterating. ๐ฉธ
---
## ๐ฏ Who this is for
You'll get value from this repo if any of these sound like you:
- ๐ง **Your single AI agent forgets everything between conversations.** VECNA gives the swarm shared, decay-aware memory across requests.
- ๐ชฆ **Your agent crashes mid-task and starts over.** VINES persists orchestration state to MariaDB; recovery walks Linear to figure out where to resume.
- ๐งฑ **One mega-agent with every tool/skill loaded eats your context window on trivial routing.** The Nexus stays lean; specialists carry their own context.
- ๐๏ธ **You want operator-grade visibility into what an autonomous agent is doing** โ without scraping logs. Linear (or any ticket backend) gives you a live board.
- ๐ฆ **You run OpenClaw** and want a drop-in upgrade from the default single-agent shape.
If you're prototyping a one-shot Q&A bot, this is overkill. Reach for it when you need _durability_, _specialisation_, and _operator oversight_ โ not just "an agent that calls tools."
---
## ๐ธ๏ธ Architecture (the Hive-Mind hierarchy)
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ผ The Nexus (orchestrator:main) โ
โ - Talks to the operator โ
โ - Decides who handles what โ
โ - Drives The Pulse end-to-end โ
โ - Synthesises + reports โ
โโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโ
โ openclaw agent --agent <id> --message "..."
โโโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ โ โ โ
โโโโโโผโโโโ โโโโโโผโโโโโ โโโโโผโโโโโโ โโโโผโโโโโ โโโโโผโโโโโ
โ๐งsystemโ โโจ๏ธ code โ โ๐researchโ โ๐ dataโ โ โฆ six โ
โ agent โ โ agent โ โ agent โ โ agent โ โtendrilsโ
โโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโ โโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโ
โ ๐ง The Hive โ durable memory โ
โ โข vines_ledger (orchestration โ
โ state, per request) โ
โ โข vecna_hive (shared knowledge) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
Three layers, full vocabulary in [`docs/branding.md`](docs/branding.md):
- **The Nexus** โ the orchestrator. Operator talks only here.
- **The Tendrils** โ the six specialists. `system-agent`, `code-agent`, `research-agent`, `data-agent`, `comm-agent`, `vision-agent`.
- **The Hive** โ MariaDB-backed persistence. VINES (orchestration state) + VECNA (shared knowledge fragments, see [`vecna/spec.md`](vecna/spec.md)).
---
## ๐ Three ways to install
### ๐ As an OpenClaw plugin (recommended)
โก **Two commands** if you already have OpenClaw โฅ 2026.5.0 and a reachable MariaDB. This is the fastest path and the one you should use unless you specifically want to work from source.
```bash
# 1. Install from ClawHub (npm fallback works too)
openclaw plugins install clawhub:openclaw-hawkins \
|| openclaw plugins install npm:openclaw-hawkins
# 2. Provision schemas + the 6 specialist agents in one shot
openclaw hawkins setup
```
โจ The plugin registers **12 typed tools** (`vines_*` ร 6, `vecna_*` ร 6) with the OpenClaw runtime. They become available to agents that have been granted access in your OpenClaw config โ restrict to the intended Hawkins agents (Nexus + the 6 Tendrils) where possible and review tool calls for sensitive mutations. The `hawkins setup` command prints an exhaustive **post-install banner** listing every tool, verification commands, and the remaining personalisation steps, so a human operator _or_ an AI installer agent can finish the install without consulting any other doc.
Configure the plugin via `openclaw config`:
```bash
openclaw config set plugins.entries.openclaw-hawkins.config.mariadb.url "mariadb://your-host:3306/hawkins"
openclaw config set plugins.entries.openclaw-hawkins.config.mariadb.user "hawkins"
openclaw config set plugins.entries.openclaw-hawkins.config.mariadb.ssl "insecure" # for self-signed cloud certs
# Password MUST come from the gateway env โ the plugin schema refuses to store it in openclaw.json.
```
๐ **Secrets policy:** `MARIADB_PASSWORD` and `LINEAR_API_KEY` are read from the gateway's environment only โ never from `openclaw.json`. The plugin's config schema deliberately rejects them. Wire them via a 0600 systemd `EnvironmentFile` (the post-install banner shows the exact recipe), or feed them from 1Password using the SKILL.md recipe.
---
### ๐ค Let an AI agent install it for you
> โก **This repo ships with a [`SKILL.md`](SKILL.md)** โ an OpenClaw skill manifest that any capable agent (your existing OpenClaw orchestrator, or any AI assistant with shell access on the host) can use to install and configure this pattern end to end.
๐ช **Step 1.** Drop the skill into your workspace:
```bash
mkdir -p ~/.openclaw/workspace/skills/openclaw-hawkins-installer
curl -fsSL https://raw.githubusercontent.com/parijatmukherjee/openclaw-hawkins/v1.0.9/SKILL.md \
> ~/.openclaw/workspace/skills/openclaw-hawkins-installer/SKILL.md
```
๐ฌ **Step 2.** Ask your agent: _"Install openclaw-hawkins on this host."_
โจ The skill walks the agent through prerequisite checks, repo clone, agent creation, workspace overlay, optional Linear wiring, and end-to-end smoke tests. It asks the personalisation questions (Nexus name, vibe, host facts) before making any changes.
---
### ๐ง Install it yourself (from source)
โฑ๏ธ The from-source path takes ~5 minutes โ useful when working on a feature branch or air-gapped host:
```bash
# 1๏ธโฃ Clone โ pin to the latest release tag so the source tree is immutable
git clone --branch v1.0.9 --depth 1 https://github.com/parijatmukherjee/openclaw-hawkins.git ~/openclaw-hawkins
cd ~/openclaw-hawkins
# 2๏ธโฃ Create the 6 specialist agents
./scripts/setup.sh
# 3๏ธโฃ Personalise each specialist's identity
for id in system-agent code-agent research-agent data-agent comm-agent vision-agent; do
cp agents/$id/IDENTITY.md.template ~/.openclaw/agents/$id/workspace/IDENTITY.md
done
# 4๏ธโฃ Install the Nexus's workspace files
cp orchestrator/AGENTS.md ~/.openclaw/workspace/AGENTS.md
cp orchestrator/TOOLS.md.template ~/.openclaw/workspace/TOOLS.md # then edit
cp orchestrator/IDENTITY.md.template ~/.openclaw/workspace/IDENTITY.md # then edit
# 5๏ธโฃ Restart and smoke-test
openclaw gateway restart
openclaw agent --agent system-agent --message "Introduce yourself in one line." --json --timeout 30
```
๐ Full step-by-step (Linear + VINES) lives in **[INSTALL.md](INSTALL.md)**.
---
## โ
Prerequisites
**The minimum (Nexus + Tendrils, no Hive):**
- ๐ **OpenClaw โฅ 2026.5.7** with the gateway running. Check: `openclaw --version` and `openclaw gateway status`.
- ๐ง **At least one model with auth.** Defaults assume `ollama/kimi-k2.6:cloud` (text) and `ollama/kimi-k2.5:cloud` (vision). Substitute OpenAI / Groq / any Anthropic-compatible provider via env vars to `setup.sh`.
**Optional add-ons:**
- ๐ A **Linear** account (any plan) if you want ticket oversight. The CLI reads its API key from `$LINEAR_API_KEY` by default; if you'd rather keep the key in 1Password, the [`op` CLI](https://developer.1password.com/docs/cli/) is a supported fallback (see `orchestrator/LINEAR.md`). Neither `op` nor a 1Password account is required.
- ๐ข **Node โฅ 20** + a **MariaDB** instance (local or cloud โ TLS supported including self-signed via `MARIADB_SSL=insecure`) if you want **VINES**, the durable-state layer.
---
## ๐ The Pulse (how dispatch flows)
When the Nexus decides a request isn't trivial, it enters **The Pulse**. Five named phases:
```
operator request
โ
๐ฉธ Sensitivity Check โ does this need the full protocol? (vines triage)
โ (yes)
๐ฉธ Anchoring โ parent Linear ticket + VINES row (lin
... (truncated)
tools
Comments
Sign in to leave a comment