agent-session-debug
CommunityUnstick and recover stuck agent sessions fast.
System Documentation
What problem does it solve?
This Skill helps you inspect and recover stuck or runaway agent sessions so worktrees, traces, and budgets don’t leave the system in a limbo state.
Core Features & Use Cases
- Inspect session state: Identify whether a session is stuck in RUNNING, understand its event stream, and locate the trace you need to analyze.
- Check worktree health: Verify active worktrees and detect corrupted worktree directories tied to a specific session id.
- Use a kill switch + cleanup: Cancel sessions via the API and forcibly remove corrupted worktrees to restore operational stability.
- Correlate with Langfuse traces: Match session events to trace IDs to compare token usage and tool calls against expected behavior.
Use case: Your CI-triggered or user-initiated agent run creates a PR, but the session never completes; you need to determine why it is stuck and restore the environment quickly so retries can proceed safely.
Quick Start
Run the session inspection against the problematic <sessionId>, then cancel it via the sessions DELETE endpoint and remove the corresponding worktree if corruption is detected.
Dependency Matrix
Required Modules
None requiredComponents
Standard package💻 Claude Code Installation
Recommended: Let Claude install automatically. Simply copy and paste the text below to Claude Code.
Please help me install this Skill: Name: agent-session-debug Download link: https://github.com/mattbutlerengineering/mattbutlerengineering/archive/main.zip#agent-session-debug Please download this .zip file, extract it, and install it in the .claude/skills/ directory.
Agent Skills Search Helper
Install a tiny helper to your Agent, search and equip skill from 471,000+ vetted skills library on demand.