🔌Services & Utilities/bundled
Bundled Skill: stuck
src/skills/bundled/stuck.ts
Prompt Engineering Insight
Reliability field guide for frozen sessions—process state, child processes, RSS, and optional sampling—framed as a report back to an internal channel.
Techniques Used
step-by-steptool-use-guidancebehavioral-constraints
prompt
/stuck — diagnose frozen/slow Claude Code sessions
The user thinks another Claude Code session on this machine is frozen, stuck, or very slow. Investigate and post a report to #claude-code-feedback.
What to look for
Scan for other Claude Code processes (excluding the current one — PID is in \
process.pid\ but for shell commands just exclude the PID you see running this prompt). Process names are typically \claude\ (installed) or \cli\ (native dev build).Signs of a stuck session:
- High CPU (≥90%) sustained — likely an infinite loop. Sample twice, 1-2s apart, to confirm it's not a transient spike.
- Process state \
D\(uninterruptible sleep) — often an I/O hang. The \state\column in \ps\output; first character matters (ignore modifiers like \+\, \s\, \<\). - Process state \
T\(stopped) — user probably hit Ctrl+Z by accident. - Process state \
Z\(zombie) — parent isn't reaping. - Very high RSS (≥4GB) — possible memory leak making the session sluggish.
- Stuck child process — a hung \
git\, \node\, or shell subprocess can freeze the parent. Check \pgrep -lP <pid>\for each session.
Investigation steps
- 1. List all Claude Code processes (macOS/Linux):
\
\\` ps -axo pid=,pcpu=,rss=,etime=,state=,comm=,command= | grep -E '(claude|cli)' | grep -v grep
\
\\` Filter to rows where \
comm\ is \claude\ or (\cli\ AND the command path contains "claude").- 2. For anything suspicious, gather more context:
- Child processes: \
pgrep -lP <pid>\ - If high CPU: sample again after 1-2s to confirm it's sustained
- If a child looks hung (e.g., a git command), note its full command line with \
ps -p <child_pid> -o command=\ - Check the session's debug log if you can infer the session ID: \
~/.claude/debug/<session-id>.txt\(the last few hundred lines often show what it was doing before hanging)
- 3. Consider a stack dump for a truly frozen process (advanced, optional):
- macOS: \
sample <pid> 3\gives a 3-second native stack sample - This is big — only grab it if the process is clearly hung and you want to know *why*
Report
Only post to Slack if you actually found something stuck. If every session looks healthy, tell the user that directly — do not post an all-clear to the channel.
If you did find a stuck/slow session, post to #claude-code-feedback (channel ID: \
C07VBSHV7EV\) using the Slack MCP tool. Use ToolSearch to find \slack_send_message\ if it's not already loaded.Use a two-message structure to keep the channel scannable:
- 1. Top-level message — one short line: hostname, Claude Code version, and a terse symptom (e.g. "session PID 12345 pegged at 100% CPU for 10min" or "git subprocess hung in D state"). No code blocks, no details.
- 2. Thread reply — the full diagnostic dump. Pass the top-level message's \
ts\as \thread_ts\. Include: - PID, CPU%, RSS, state, uptime, command line, child processes
- Your diagnosis of what's likely wrong
- Relevant debug log tail or \
sample\output if you captured it
If Slack MCP isn't available, format the report as a message the user can copy-paste into #claude-code-feedback (and let them know to thread the details themselves).
Notes
- Don't kill or signal any processes — this is diagnostic only.
- If the user gave an argument (e.g., a specific PID or symptom), focus there first.
Tags
skillsbundled