A diagnostic utility designed to identify and troubleshoot frozen or abnormally slow local AI agent sessions through process-level analysis.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install stuck-session-diagnosis
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install stuck-session-diagnosis using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Stuck Session Diagnosis?
The Stuck Session Diagnosis skill is a specialized utility within the Openclaw Skills ecosystem designed to maintain the health of your development environment. When an AI agent session becomes unresponsive or slow, this skill provides a structured way to investigate the root cause without resorting to blind restarts. It analyzes system-level metrics such as CPU usage, resident set size (RSS), and process uptime to determine if a session is truly hung or just performing intensive tasks. By integrating this into your workflow, you gain deep visibility into the execution state of your local agents, ensuring that performance bottlenecks are identified and resolved efficiently.
Stuck Session Diagnosis Use Cases
- Investigating a Claude Code session that has stopped responding to inputs.
- Identifying which local agent process is consuming excessive system resources.
- Generating technical reports for debugging intermittent agent hangs.
- Differentiating between a transient performance spike and a sustained process deadlock.
How Stuck Session Diagnosis Works
- Scan the local system to identify all candidate agent processes currently running.
- Collect baseline performance metrics including CPU load, memory (RSS) consumption, and process state.
- Perform secondary sampling of suspicious processes to confirm if performance issues are persistent.
- Analyze associated debug logs and child process hierarchies to find hidden bottlenecks.
- Generate a detailed, actionable report containing the diagnosis and supporting evidence for further troubleshooting.
Stuck Session Diagnosis Setup
To use this skill within your local environment, ensure your agent framework is updated to include the latest Openclaw Skills library. The skill is typically available as a bundled diagnostic tool.
# Check the status of the diagnostic skill
openclaw skills list --detailed
# Run a diagnosis on a suspected frozen session
openclaw run stuck_session_diagnosis
Stuck Session Diagnosis Data Schema & Taxonomy
The skill generates a structured report based on process telemetry and log analysis. Data is organized into the following schema:
| Metric | Type | Description |
|---|---|---|
| PID | Integer | The system process ID of the suspected agent. |
| RSS | String | Resident Set Size indicating memory usage. |
| CPU_Load | Percentage | Current CPU utilization of the specific PID. |
| Status | String | Current process state (e.g., Running, Sleeping, or Zombie). |
| Evidence | Log Data | Snippets from debug logs and process tree snapshots. |
Stuck Session Diagnosis Advanced Features
- Sustained sampling confirms if issues are persistent or just temporary spikes to prevent false positives.
- Automated log inspection correlates system metrics with agent debug outputs for deeper context.
- Process tree analysis maps parent/child relationships to find hidden deadlocks in background threads.
- Escalation-ready output provides a concise and actionable summary for developer support or engineering teams.
SKILL.md
Loading
Related Openclaw Skills
Workflow Skillify
An intelligent meta-skill that converts successful AI interactions and repeatable processes into formal, reusable skill documentation.
Sports Betting Analyzer
An intelligent sports analysis assistant that leverages machine learning and historical data to provide probability-based match predictions and betting decision support.
CISSPly API
A comprehensive CISSP exam preparation API that delivers randomized questions and real-time performance analytics for cybersecurity professionals.
Klarity Health Booking Guide
An intelligent navigation tool for booking licensed psychiatric evaluations and telehealth appointments via the Klarity Health marketplace.
Verifier Skill Generator
Automate the creation of project-specific verifiers for web, CLI, and API runtime checks to streamline AI-driven verification.
Statusline Setup
A specialized tool to synchronize Claude Code's statusline UI with your existing shell prompt configuration for a seamless terminal experience.
Featured*
