queen-colony-debug

queen-colony-debug is a skill for Claude Code from aden-hive/hive. It costs 0 tokens per session (4,455 once invoked), scanned C, original, Apache-2.0.

A troubleshooting procedure for the Hive system that coordinates a main session, worker sessions, and a tracking database. It focuses on finding failures in how these parts create, share, and resume work.

In plain words
What is it for?
Use it to debug or verify the pipeline that creates colonies, registers tracking data, starts parallel workers, and resumes sessions from disk.
Why use it?
It helps investigate problems without changing the user's real Hive Desktop data by using an isolated test environment first. It also gives a structured way to check issues such as missing database tables, invisible worker data, or unexpected session folders.

Skill for Claude Code

Written for Claude Code: installed under .claude/.

Not installable: its command points at a path on the author’s own machine, so it runs nowhere else. The line is /Users/aden/Library/Application.

Good fit Use it to debug or verify the pipeline that creates colonies, registers tracking data, starts parallel workers, and resumes sessions from disk.

Compare 6 skills from other repositories ↓
About the project

OpenHive is a runtime for groups of specialized AI agents that collaborate on long-running business processes. A persistent lead agent, called the Queen, creates and coordinates worker agents while the system manages state, recovery, observability, costs, and human oversight. The catalogue entries provide agent skills, instructions, and integrations for working with this harness.

aden-hive/hive · 11,021 stars · on GitHub

Install

Getting it into your agent

There is no command for this one: it runs only inside a plugin, and the catalogue could not identify which plugin ships it. The source is linked below.

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for queen-colony-debug

README.md
[![agentmods](https://agentmods.dev/badge/skills/aden-hive/hive/queen-colony-debug.svg)](https://agentmods.dev/skills/aden-hive/hive/queen-colony-debug)
Your own site
<a href="https://agentmods.dev/skills/aden-hive/hive/queen-colony-debug"><img src="https://agentmods.dev/badge/skills/aden-hive/hive/queen-colony-debug.svg" alt="Measured on agentmods" height="20"></a>
Per session 0 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 4,455 The whole file, excluding the scripts and references it only reads on demand.
Security scan C 2 findings. A grade says what 26 rules found in the file — not that it is safe.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5.1 $0.00000 $0.04455
Opus 5 $0.00000 $0.02227
Sonnet 5 $0.00000 $0.00891
Haiku 4.5 $0.00000 $0.00445

Measured 8d ago against content hash aa7001b1fbe9, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-07, from the pricing page.

Security

Grade C, and why

queen-colony-debug scanned grade C with 2 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 8d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Recursive force deletehighDestructive command

rm -rf with a variable or a broad path is one typo away from removing the wrong tree.

If you used `HIVE_HOME=/tmp/hive_e2e`, optionally `rm -rf /tmp/hive_e2e` when done.

Makes network callslowCapability

Not a fault in itself. Listed so you know the mod talks to something, and to what.

until curl -sf http://127.0.0.1:$PORT/api/health >/dev/null 2>&1; do sleep 1; done
.claude/skills/queen-colony-debug/SKILL.md · 332 lines

How it starts

The opening of the file, as written. The whole thing — 332 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Queen / Colony Debug Skill

SOP for live debugging of queen sessions, colony forks, worker spawns, and tracker DB plumbing without touching the user's production Hive Desktop. Use this when something is wrong in the create_colony → tracker → run_parallel_workers → worker pipeline.

Trigger

User asks you to debug, reproduce, or verify behavior in:

  • Queen DM sessions, colony sessions, fork_session_into_colony
  • ColonyBinding propagation (queen exec context, worker input_data)
  • tracker_sql / tracker_register_writable / tracker_upsert / tracker_query
  • run_parallel_workers preflight
  • Phantom colonies/session_<uuid>/ shadow folders (the original split-brain bug)
  • Session resume from disk, queen phase transitions (independent → incubating → colony)

Examples: "queen says no such table", "workers can't see what queen wrote", "phantom colony folder appeared", "verify my colony refactor didn't break anything".

Hard rules

  1. Never run against the user's real Hive Desktop runtime by default. Use an isolated HIVE_HOME=/tmp/hive_e2e first. Only switch to the real HIVE_HOME (~/Library/Application Support/Hive/users/<hash>) when the user has explicitly asked for live LLM verification or when an offline repro is impossible.
  2. Never read the real secrets/, credentials/, or configuration.json directories. The auto-mode classifier will block credential exploration. You don't need their contents — the server reads them itself.
  3. Pick a non-default port (--port 8901/8902/8903) so you don't collide with a running Hive Desktop on 8787.
  4. Background the server, don't foreground it. & redirects the log to a file you can tail/grep while you make HTTP calls in parallel.
  5. For "wait for thing X" patterns: use Bash run_in_background:true with an until grep -q ... loop — never chain sleep N. The harness blocks long leading sleeps.
  6. LLM-driven turns cost real credits. Budget your queen prompts: prefer terse, deterministic instructions ("just call create_colony with these exact args") over open-ended questions.

Read the full file on GitHub · 332 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 8d ago First seen · 332 lines · 0 tokens per session scan C aa7001b1fbe9

Subscribe to this mod's changes

queen-colony-debug is a skill published in the GitHub repository aden-hive/hive (11,021 stars, last pushed yesterday), licensed Apache-2.0. It costs nothing until one of its globs matches a file; then it loads 4,455 tokens. A static security scan graded it C with 2 findings (recursive force delete, makes network calls). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Related

Other skills, from other repositories

loop-triage

Triage recent CI failures, open issues, and recent commits into a prioritized, actionable picture. Reads the prior STATE.md as memory and rewrites it. The maker half of the loop.

SUDARSHANCHAUDHARI/MyLoop · 43 tokens

ast-analyzer

Deep Abstract Syntax Tree analysis for understanding code structure, dependencies, impact analysis, and pattern detection at the structural level across multiple programming languages.

bejranonda/LLM-Autonomous-Agent-Plugin-for-Claude · 30 tokens

validation-standards

Tool usage requirements, failure patterns, consistency checks, and validation methodologies for Claude Code operations.

bejranonda/LLM-Autonomous-Agent-Plugin-for-Claude · 22 tokens

code-analysis

Provides methodologies, metrics, and best practices for analyzing code structure, complexity, and quality.

bejranonda/LLM-Autonomous-Agent-Plugin-for-Claude · 20 tokens

diagnose-why-work-stopped

How to handle "why did this work stop / why is this looping?" assignments. Forensics first on the named tree, surface the exact stop-point, frame the fix as a general product rule that respects three invariants (productive work continues, only real blockers stop work, no infinite loops), and deliver a plan — no code…

aimerdoux/wavex-os · 114 tokens

evidence-collector

Skill "evidence-collector" from aimerdoux/wavex-os, covering qa agent personality, 🧠 your identity & memory, 🔍 your core beliefs, "screenshots don't lie" and "default to finding issues".

aimerdoux/wavex-os · 0 tokens