Use this skill when a shell command is likely to produce long output, keep running, refresh continuously, or require structured monitoring instead of raw stdout.

Invoke When

• The command may print more than a small screen of output
• The command may run for a long time
• The command may stream continuously, such as watch, top, tail -f, ping, or log followers
• The command fails and you need a lightweight scan instead of manually reviewing a large log

Core Behavior

• Always write stdout and stderr to a timestamped log file
• Return a compact status card instead of raw full output
• Truncate long previews by default and point to the log file for deeper inspection
• Preserve timestamps so you can inspect the latest state or a specific time window
• Offer a lightweight scan step for locating likely errors, warnings, and failures

Tools

long_context_shell_run

Run a shell command in a detached process with file-backed logging.

Inputs

• command (string, required): shell command to run
• waitMs (number, optional): how long to wait before returning an initial status card
• background (boolean, optional): force monitor-first mode and return quickly for later peeks
• headLines (number, optional): lines to show from the beginning of the log
• tailLines (number, optional): lines to show from the end of the log

Behavior

• Start the command through the platform shell
• Write stdout and stderr to a log file with timestamps
• If background is true, prefer a short initial wait and return control quickly
• Return a status card with session id, log path, line count, byte count, status, background mode, and truncated preview
• If the command still runs, use long_context_shell_peek later instead of rerunning the command

long_context_shell_peek

Read the latest state of an existing session or log file.

Inputs

• sessionId (string, optional): previously returned session id
• logPath (string, optional): direct path to a log file if session id is unavailable
• headLines (number, optional): lines to show from the beginning
• tailLines (number, optional): lines to show from the end
• timeQuery (string, optional): timestamp fragment to filter lines, such as 2026-03-24T10:15

Behavior

• Resolve the session or log file
• Detect whether the process is still running or already exited
• Return a compact status card with truncated preview
• If timeQuery is present, return matching lines for that timestamp fragment

long_context_shell_scan

Scan a large log for likely failures instead of manually reading the full file.

Inputs

• sessionId (string, optional): previously returned session id
• logPath (string, optional): direct path to a log file
• patterns (array of strings, optional): custom match patterns
• contextLines (number, optional): surrounding lines to include around each match
• limit (number, optional): maximum number of matches to return

Behavior

• Search the log for strong failure signals such as error, exception, failed, fatal, and timeout
• Rank matches by severity so likely root-cause lines appear before generic warnings
• Return the strongest matches with line numbers, severity, and short context
• Prefer this tool over manual full-log inspection when output is large

long_context_shell_stop

Stop a running session when monitoring is no longer needed.

Inputs

• sessionId (string, required): session to stop

Recommended Workflow

• Use long_context_shell_run for long or continuous commands
• If status is running, use long_context_shell_peek to monitor progress
• If status is failed or the preview is too short to explain the problem, use long_context_shell_scan
• Only read the full log manually when the scan still leaves important ambiguity

Debug Tips

• Start with a small waitMs and inspect the first status card before increasing complexity
• If a command is expected to keep running, set background: true and observe with repeated long_context_shell_peek
• Use timeQuery with the startedAt timestamp prefix to zoom into a suspicious time slice without reading the whole log
• If preview is truncated, treat logPath as the source of truth and use scan before opening the whole file
• If scan misses the real issue, retry with custom patterns that match the toolchain, framework, or service you are debugging
• When shell quoting gets tricky, first validate the raw command directly in the terminal, then move the exact command string into long_context_shell_run
• Prefer short self-contained repro commands such as node -e or a tiny script file when debugging behavior across shells
• Remember that shell syntax can differ across Unix and Windows, so commands using pipes, redirects, or quoting may need platform-specific forms
• For continuous commands, always finish the debug loop with long_context_shell_stop so old sessions do not keep running in the background
• To review a human-readable end-to-end scenario, run node manual-flow-test.js and inspect the printed status cards and scan output

Safety

• Do not run destructive commands without explicit user approval
• Ask before using commands that delete files, reformat disks, reboot the machine, or escalate privileges
• Prefer long_context_shell_scan over full-log manual review when output is large
• Use long_context_shell_stop when a continuous command is no longer needed, especially for tail -f, watch, or similar monitoring sessions

Examples

• Long build:

• Continuous output:

• Check latest state:

• Check a specific timestamp:

• Scan failures:

• Human-readable flow test: