hivemind

Hivemind

Hivemind is a RAG-powered marketing AI with four specialist personas and a curated knowledge base. This skill exposes three APIs:

• Chat (hivemind) — send a prompt to a persona, get a response, list resumable conversations, or run the chat health check.
• Knowledge search (hivemind-search) — RAG retrieval without the LLM layer.
• Projects (hivemind-project) — list/create/poll/update projects used as chat context.

All three scripts auto-load credentials from ~/.config/hivemind/env (chmod 600). Never echo or log API keys.

Heads up: project auto-scoping. If HIVEMIND_PROJECT_ID is set in the env file, every hivemind chat and hivemind-search call attaches it by default, which can cause personas to refuse prompts that don't match the project's scope. Pass --no-project on an individual call to bypass the env default, or --project <uuid> to switch to a different project for that call. Project scope only affects chat context — hivemind-search corpus is global regardless.

Script paths

The scripts live inside this plugin. Resolve them relative to this skill directory:

Tool	Relative path
hivemind	scripts/hivemind
hivemind-search	scripts/hivemind-search
hivemind-project	scripts/hivemind-project

Claude Code and Codex may install the plugin in different locations, so avoid relying on a Claude-specific environment variable when resolving paths. Examples below use short names (hivemind, hivemind-search, hivemind-project) for readability. If the user also installed the CLIs on their PATH via install.sh, the short names work directly in a terminal.

Picking a Persona

Persona	CLI alias	Use for
ghostwriter	ghostwriter	Writing copy: headlines, CTAs, taglines, landing pages, ad copy, emails, onboarding text, product descriptions
genius-strategist	strategist	Strategy: positioning, market analysis, competitive intel, messaging frameworks, value propositions, audience segmentation
gtm-architect	gtm	Tactics: launch plans, channel strategy, campaign calendars, funnels, budget allocation, KPI frameworks
general-assistant	general	General marketing questions that don't fit the other three

Either the canonical ID or the CLI alias works in --persona.

Decision rules:

• "Write / draft / rewrite ..." → ghostwriter
• "Analyze / evaluate / position / compare ..." → strategist
• "Plan / launch / campaign / roadmap ..." → gtm
• Multi-step work (e.g., positioning + copy): call strategist first, then feed its output into ghostwriter.
• If you're unsure, omit --persona — the API auto-classifies intent.

For the full decision tree, see references/personas.md.

Chat — Primary Workflow

# Auto-classify persona
hivemind chat "Write 3 headlines for a B2B SaaS landing page targeting CTOs"

# Force persona
hivemind chat --persona ghostwriter "Draft a Twitter thread about our launch"
hivemind chat --persona strategist "Analyze positioning vs Vercel and Netlify"
hivemind chat --persona gtm        "Build a Q2 launch plan for an API product"

# Attach a project for extra context (pulls social + intel reports server-side)
hivemind chat --persona strategist --project <uuid> "How should we respond to the competitor launch?"

# Bypass the default project from HIVEMIND_PROJECT_ID for one call
# (use if a project-scoped persona refuses your prompt as out-of-scope)
hivemind chat --no-project --persona ghostwriter "Unscoped copy request"

# Pipe long prompts via stdin (max 8000 chars)
cat brief.md | hivemind chat --persona ghostwriter

# Stream tokens for long outputs
hivemind chat --stream --persona gtm "Give me a full 90-day launch runbook"

# Full JSON including sources
hivemind chat --persona strategist --json "What positioning framework works for dev tools?"

# List conversation IDs you can resume with --conversation-id
hivemind conversations

# Health check (no auth required)
hivemind health

Conversations (persistent context): by default, every call is a fresh context. To persist context across turns, use --start-conversation on turn 1 then --conversation-id on subsequent turns. To discover existing resumable conversations for the current key, use hivemind conversations. See references/examples.md for a full example. Requires a user-attributed key and --project.

Prompt Best Practices

Give Hivemind full context — it performs materially better with structured input than with one-liners:

1. Product context — what it does, who it's for, pricing tier
2. Current state — what exists now (copy, strategy, plan) so it can improve rather than start from scratch
3. The problem — why current isn't working (data if available)
4. Deliverables — explicit list with format/length requirements
5. Audience — who will see this, what they already know, where they come from
6. Constraints — tone, voice, length, brand guidelines, budget, timeline, must-haves/must-avoids

Pipe long briefs via stdin rather than cramming into a single argument.

Knowledge Search

Use when you want source-grounded snippets without an LLM rewrite — e.g. "what does Hivemind's knowledge base say about ICP definition?".

# Simple
hivemind-search "product launch best practices"

# Persona-targeted (2-pass retrieval) + higher threshold
hivemind-search --persona strategist --threshold 0.5 --max 15 "competitive positioning frameworks"

# Full JSON (chunks with metadata)
hivemind-search --json "email subject line openings" | jq

Key flags (see hivemind-search --help for all):

• --threshold 0.0-1.0 — relevance cutoff (0.4 default; raise for tighter matches)
• --max 1-25 — result count cap
• --persona ID — enables persona-specific 2-pass ranking
• --no-rerank — skip LLM reranking (faster, cheaper, lower quality)

Knowledge search is not filtered by --project — the corpus is global. --project only gates endpoint access for project-scoped keys.

Projects

Projects are containers for company context that Hivemind pulls into chat prompts (social media reports, intelligence reports). Create once, reuse via --project <id>.

# Create — returns immediately, enrichment runs async in the background
hivemind-project create \
  --url https://example.com \
  --name "My Project" \
  --description "A SaaS platform for..." \
  --stage launch \
  --type "SaaS,AI / ML"

# Poll until enrichment completes (or fails)
hivemind-project wait <project-id>

# List accessible projects
hivemind-project list

# Fetch current state
hivemind-project get <project-id>

# Patch fields (strict schema — unknown fields return 400)
hivemind-project update <project-id> \
  --stage growth \
  --audiences "developers,enterprise"

# Clear a field
hivemind-project update <project-id> --clear legal_considerations
hivemind-project update <project-id> --clear-list audiences

List flags take a single quoted comma-separated string (--audiences "a,b,c"), not separate args. Use --clear-list FIELD to send [].

Field limits. The CLI preflights these locally before calling the API. Source of truth: lib/validation-schemas/api-project-schemas.ts in the hive-mind repo.

Field (flag)	Per-item	Array max	Notes
description	5000 chars	—	string
objectives	240 chars	10 items
audiences	25 chars	5 items
chains	25 chars	10 items
channels	25 chars	10 items
geographics	25 chars	5 items
project_type (--type)	2-50 chars	4 items	free-form (any string)
stage	—	—	enum: idea, pre-launch, launch, growth, scale, n/a

Creating / updating projects requires a user-attributed API key. Unattributed (legacy) keys can only get.

Handling Errors

All three CLIs exit non-zero on failure and print the error code + message to stderr. Common cases:

Error	Meaning	What to do
invalid_key / missing_api_key	Key wrong or missing	Check ~/.config/hivemind/env; request a new key if revoked
rate_limited (429)	Per-minute window exceeded	Wait Retry-After seconds (printed in response)
monthly_quota_exceeded (429)	Monthly cap hit	Wait for 1st-of-month reset or request a cap increase
project_access_denied (403)	Key isn't attributed to the project's owner	Verify the right key/project pairing
validation_error (400)	Bad input	Read the details array; each entry names the field + reason
text_too_long (400)	Prompt > 8000 chars	Shorten or summarize; split into multiple requests

Full error reference: references/errors.md.

Quota Awareness

Default monthly caps per key: 100 chat, 200 search, 10 project creates, 50 project updates. If you're running multiple agents against the same key, note that every successful call consumes a quota unit — keep usage intentional.

References

• references/api-reference.md — full request/response schemas, headers, streaming protocol
• references/personas.md — extended persona guide + prompt archetypes
• references/errors.md — every error code with remediation
• references/examples.md — end-to-end workflows (multi-step, streaming parser, project + chat)

Requesting an API Key

Users without a key should fill out the request form:

https://myosin.typeform.com/api-request

Approval is typically one business day. Keys are shown only once — save immediately.