- name
SKILL.md
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add aden-hive/hive --skill terminal-tools-foundations -a cursor -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add aden-hive/hive --skill terminal-tools-foundations -a claude-code -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add aden-hive/hive --skill terminal-tools-foundations -a codex -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add aden-hive/hive --skill terminal-tools-foundations -a grok -ySend the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
Install this skill: https://github.com/aden-hive/hive/tree/HEAD/core/framework/skills/_preset_skills/terminal-tools-foundationsFrom the publisher
These tools provide command execution, background jobs, log streaming, filesystem search, and optional PTY sessions. POSIX uses bash for shell commands; Windows selects Git Bash, PowerShell, then cmd. Inspect shell_kind in results.
Use search_tools(query="inventory") before describing capabilities. It reports this session's loaded, searchable, disabled, and configured-but-unavailable tools. Load searchable tools by exact name. An absent schema alone does not prove a capability is missing; configuration does not prove credentials or connectivity work. Terminal tools and coding file tools default to the injected session workdir; an explicit absolute path overrides it.
read_file before edit_file when the coding tools are enabled; it records file state for the stale-edit guard. Otherwise use a command appropriate to shell_kind.edit_file when enabled. Replacement mode requires a unique match unless replace_all=true; patch mode validates all operations before writing. Inspect its changed-file summary and diff. Re-read files after external changes. Terminal editing remains available when coding tools are disabled.terminal_exec("cat > PATH <<'EOF' ... EOF")terminal_rg (content / regex grep) and terminal_glob (find files by name)browser_setup, read the browser skill, then run hive-browser <command> --json through terminal_exec.web_search and load it if available; verify required credentials. Do not invent a callable tool name.Every spawn-style call (terminal_exec, the auto-promoted job state) returns this shape:
{
"exit_code": 0, // null when auto-backgrounded or pre-spawn error
"stdout": "...", // decoded, truncated to max_output_kb (default 256 KB)
"stderr": "...",
"stdout_truncated_bytes": 0, // > 0 means more is in output_handle
"stderr_truncated_bytes": 0,
"runtime_ms": 42,
"pid": 12345,
"output_handle": null, // "out_<hex>" when truncated — paginate with terminal_output_get
"timed_out": false,
"semantic_status": "ok", // "ok" | "signal" | "error" — read THIS, not just exit_code
"semantic_message": null, // e.g. "No matches found" for grep exit 1
"warning": null, // e.g. "may force-remove files" for rm -rf
"auto_backgrounded": false,
"job_id": null, // set when auto_backgrounded=true
"shell_kind": "bash" // interpreter that ran it: "bash" | "powershell" | "cmd" | "direct"
}
The agent loop first waits up to five seconds for terminal_exec. A slower call returns a bg_* handle; redeem it with collect_result. The terminal's own promotion threshold defaults to 30 seconds. Past that threshold it transfers the process to its job manager and returns:
{ "auto_backgrounded": true, "exit_code": null, "job_id": "job_<hex>", ... }
When you see auto_backgrounded: true, the job is still running. When you have nothing else to do meanwhile, wait for it:
terminal_job_logs(job_id, since_offset=0, wait_until_exit=true)
→ waits until the job exits or a new message for you arrives, returns logs + status
You're not failing — you're freed up to do other work while the long task runs.
collect_result does not redeem job_id: after collecting a promoted call, use terminal_job_logs until status is exited. Track separate stdout/stderr offsets; use terminal_job_manage(action="signal_term", job_id=...) to cancel. One wait lasts up to wait_timeout_sec (at most 600, the default); prefer one long wait to repeated short ones, each of which costs a whole model turn. A wait does not extend the execution deadline. Job retrieval/management ship with basic exec; explicit job creation and PTYs require the advanced category.
timeout_sec defaults to 60 seconds from command start, including time after promotion. Expiry terminates the owned process tree; final logs report timed_out=true. A deadline at or before promotion kills inline. Set timeout_sec=0 for unlimited execution with promotion enabled. To keep execution foreground, set auto_background_after_sec=0 and a finite timeout of at most 220 seconds (or less if the caller has a smaller budget). Use managed jobs for longer waits. Jobs belong to the terminal server and do not survive its restart.
semantic_status, not raw exit_codeSeveral common commands use exit 1 for legitimate non-error states:
For these, semantic_status will be "ok" even when exit_code == 1, with semantic_message describing why ("No matches found"). For everything else, semantic_status defaults to "ok" on 0 and "error" on nonzero.
Rule: always check semantic_status first. Only fall back to exit_code when you need the exact number (e.g. distinguishing make errors).
The envelope's warning field is set when the command matches a known destructive pattern (rm -rf, git push --force, git reset --hard, DROP TABLE, kubectl delete, terraform destroy, etc.). The command still ran — the warning is informational. Use it as a "did I mean to do that?" prompt before trusting subsequent steps that depend on the side effect.
If a warning appears unexpectedly, stop and verify: was the destructive action intended, or did a path/glob slip in?
When stdout_truncated_bytes > 0 or stderr_truncated_bytes > 0, retained output exceeded the inline cap (default 256 KiB per stream). An output_handle retrieves the retained bytes for 5 minutes, subject to earlier eviction. Paginate with:
terminal_output_get(output_handle, since_offset=0, max_kb=64)
→ { data, offset, next_offset, eof, expired }
Track next_offset across calls. If expired: true, inspect saved log files first. Repeat a command only if replaying its side effects is appropriate.
The store has a 64 MiB cap with LRU eviction. Process output passes through a 4 MiB ring per stream; old bytes can be overwritten. Poll job logs promptly and check truncated_bytes_dropped. For complete build logs, redirect output to a file and inspect that file as well as the exit status.
On POSIX, terminal_exec uses direct argv execution for simple commands and /bin/bash for shell syntax or shell=True. The user's $SHELL does not select the interpreter. zsh is refused by the shell resolver. PTY sessions are POSIX-only.
Foreground commands and explicit background jobs inherit ordinary environment variables, with ZDOTDIR and ZSH_* removed from the inherited base even when env is omitted. Explicit env values are then merged and take precedence; framework-injected identity wins over an agent-supplied identity. Noninteractive shell configuration may differ from the user's interactive terminal.
shell_kind before assuming bashOn Windows the shell is resolved in priority order: Git Bash → PowerShell → cmd. Which one ran your command is reported in the envelope's shell_kind field. Bash is only available if Git for Windows is installed; otherwise you land in PowerShell (or cmd as the floor). Read shell_kind and adapt — bash idioms silently break in the others:
Practical rule: if shell_kind != "bash", prefer commands that are portable (a bare program name + args, e.g. node x.js, python -m pip install ...) or write the PowerShell/cmd-native form. Don't assume coreutils. PTY sessions (terminal_pty_*) are POSIX-only and return an "unsupported on Windows" error.
Paths under shell_kind: "bash" on Windows (Git Bash): backslashes are escape characters, so a Windows path passed verbatim gets mangled (cat C:\Users\me\x → bash reads C:Usersmex). Use forward slashes (C:/Users/me/x, which Git Bash accepts) or the MSYS form (/c/Users/me/x). Quoting a backslash path in single quotes also preserves it (cat 'C:\Users\me\x').
Pipes (|), redirects (>, <, >>), conditionals (&&, ||, ;), and globs (*, ?, [) are detected automatically. You can pass them with the default shell=False and the runtime will transparently route through /bin/bash -c and surface auto_shell: true in the envelope:
terminal_exec("ps aux | sort -k3 -rn | head -40")
→ { exit_code: 0, stdout: "...", auto_shell: true, ... }
For simple argv commands (no metacharacters) shell=False is faster and direct-execs the binary. For commands with shell features but no metacharacters that the detector catches (rare — exotic bash builtins, here-strings), pass shell=True explicitly:
terminal_exec("set -e; complicated bash logic", shell=True)
Quoted strings work either way — the detector uses shlex.split which handles "quoted args with spaces" correctly.
See references/exit_codes.md for the full POSIX + signal-induced + semantic catalog.
Required when terminal_* tools are available. Explains foreground execution, outer collect_result handles, promoted job IDs and their retrieval/cancellation, deadlines, output retention, platform shel
---name: hive.terminal-tools-foundationsdescription: Required when terminal_* tools are available. Explains foreground execution, outer collect_result handles…---# core/framework/skills/_preset_skills/terminal-tools-foundations/SKILL.mdOverview
Required when terminal_* tools are available. Explains foreground execution, outer collect_result handles, promoted job IDs and their retrieval/cancellation, deadlines, output retention, platform shell selection, and structured editing when enabled.
FAQ
Download core/framework/skills/_preset_skills/terminal-tools-foundations/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
The publisher keeps it at https://github.com/aden-hive/hive.
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.