Skip to content
Get packs

Terminal Tools Troubleshooting

Diagnoses surprising results from terminal-tools calls, such as empty output, null exit codes, and expired handles.

Source Download skill
Repository
aden-hive/hive
Stars
11,132
Licence
Apache-2.0
Files
1 file

What it does

This is a reference guide that an AI agent loads only when a terminal command tool returns something unexpected. It matches the symptom (for example empty output, exit_code null, an expired output handle, or a 'too many jobs' error) to a short list of likely causes and fixes. It tells the agent how to read the semantic status fields and when a warning is informational rather than a failure.

Great for

  • Developers building or debugging agents that run shell commands through the terminal-tools interface
  • Anyone troubleshooting why a background job, PTY session, or output capture behaved unexpectedly

Skip it if

  • General coding or shell help outside the terminal-tools interface, since the recipes only cover that tool's behaviour
  • Environments that need the agent to run commands unattended without review, because the file itself notes that warnings are a prompt to verify side effects

Try asking

  • “My terminal_job call returned empty stdout with no error. What could be causing it?”
  • “Why is exit_code null on this command?”
  • “My output_handle says expired. How do I avoid that next time?”
  • “I get 'too many jobs' when starting commands. How do I free up slots?”
Step-by-step guide: how to use Terminal Tools TroubleshootingInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 1 original files, the Apache-2.0 licence and an attribution note.

    terminal-tools-troubleshooting.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip terminal-tools-troubleshooting.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip terminal-tools-troubleshooting.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Load this skill only when a specific symptom appears, as its description advises, rather than preloading it.
  • Check semantic_status and semantic_message before treating a non-zero exit code as a failure.
  • Review any warning flags before continuing, since they often signal a destructive command like rm -rf or git push --force.

What's inside

  • SKILL.md

Redistributed unmodified from aden-hive/hive under the Apache-2.0 licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.