hive-debugger
Interactive debugging companion for Hive agents - identifies runtime issues and proposes solutions
npx skills add majiayu000/claude-skill-registry --skill hive-debugger-aden-hive-hive --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
An interactive debugging companion for Hive agents that analyzes runtime logs at three levels (L1/L2/L3), categorizes issues, and provides actionable fix recommendations.
How it works
- When to use: Trigger with "/hive-debugger" for failing agents, understanding retries, failing tool calls, stalls, or real-time monitoring during development.
- Workflow stages: Setup/context gathering, Mode Selection (Real-time, Post-Mortem, Historical), Triage (identify runs needing attention via MCP tool), Diagnosis (per-node failures and patterns), Root Cause Analysis (detailed log scrutiny), and Fix Recommendations.
- Stage 1 collects agent name, working directory, goal, constraints, and graph nodes/edges from agent.json and exports paths.
- Stage 2 presents three modes via AskUserQuestion and stores the chosen mode.
- Stage 3 uses query_runtime_logs with status needs_attention to surface problematic runs, listing run IDs, status, and categories; prompts which run to inspect.
- Stage 4 queries per-node details with query_runtime_log_details, then categorizes issues using the provided taxonomy (Missing Outputs, Tool Errors, Retry Loops, Guard Failures, Stalled Execution, High Latency, Client-Facing Issues, Edge Routing Errors, Memory/Context Issues, Constraint Violations).
- Stage 5 uses query_runtime_log_raw for detailed evidence per problem node to explain root cause.
- Stage 6 proposes fix recommendations using structured templates (Missing Outputs, Retry Loops, Tool Errors, Edge Routing, Stalled Execution).
When to use it
- Use when your Hive agent is failing or giving unexpected results
- Use to understand why a specific node is retrying or a tool call is failing
- Use to monitor behavior in real-time during development
- Forever-alive agents (terminal_nodes=[]): focus on node visit quality and loop iterations rather than terminal completion
What it can touch
- Reads agent workspace and logs from:
exports/{agent_name}/agent.jsonand~/.hive/agents/{agent_name}/ - Uses MCP tool calls:
query_runtime_logs,query_runtime_log_details,query_runtime_log_raw(as described in the workflow steps) - Files touched in recommendations point to:
exports/{agent_name}/nodes/{node_name}.pyandexports/{agent_name}/agent.jsonwhen proposing fixes
Caveats
- Behavior and outputs depend on the agent's actual logs and the MCP tool responses
- Forever-alive agents generate different normal patterns (in_progress/paused) and should be interpreted accordingly
- The guidance strictly follows the taxonomy and templates provided in the skill workflow
# Hive Debugger An interactive debugging companion that helps developers identify and fix runtime issues in Hive agents. The debugger analyzes runtime logs at three levels (L1/L2/L3), categorizes issues, and provides actionable fix recommendations. ## When to Use This Skill Use `/hive-debugger` when: - Your agent is failing or producing unexpected results - You need to understand why a specific node is retrying repeatedly - Tool calls are failing and you need to identify the root cause - Agent execution is stalled or taking too long - You want to monitor agent behavior in real-time during development This skill works alongside agents running in TUI mode and provides supervisor-level insights into execution behavior. ### Forever-Alive Agent Awareness Some agents use `terminal_nodes=[]` (the "forever-alive" pattern), meaning they loop indefinitely and never enter a "completed" execution state. For these agents: - Sessions with status "in_progress" or "paused" are **normal**, not failures - High step counts, long durations, and many node visits are expected behavior - The agent stops only when the user explicitly exits — there is no graph-driven completion - Debug focus should be on *
- When to Use This Skill
- Forever-Alive Agent Awareness
- Prerequisites
- Workflow
- Stage 1: Setup & Context Gathering
- Stage 2: Mode Selection
- Stage 3: Triage (L1 Analysis)
- Stage 4: Diagnosis (L2 Analysis)
- Stage 5: Root Cause Analysis (L3 Analysis)
- Stage 6: Fix Recommendations
- Stage 7: Verification Support
- MCP Tool Usage Guide
- Three Levels of Observability
- Session & Checkpoint Tools
hive tui
What does the hive-debugger skill do?
Interactive debugging companion for Hive agents - identifies runtime issues and proposes solutions
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill hive-debugger-aden-hive-hive --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.