ct-debug-skill

Diagnose claude-threads coordination issues with bash-based health checks and remediation workflows.

Updated Dec 24, 2025
One-click install
npx skills add https://github.com/hanibalsk/claude-threads --skill ct-debug-skill
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ct-debug-skill
Source: https://github.com/hanibalsk/claude-threads/tree/main/skills/ct-debug
Command: npx skills add https://github.com/hanibalsk/claude-threads --skill ct-debug-skill

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you diagnose and troubleshoot issues in claude-threads, including orchestrator, threads, worktrees, events, databases, and agent coordination, reducing diagnosis time and complexity.

Core Features & Use Cases

  • System-wide health checks: Verify orchestrator, API, and database health to surface issues early.
  • Thread & Worktree diagnostics: Inspect thread status, logs, and orphaned worktrees to restore normal operation.
  • Event and API troubleshooting: Filter events and monitor API endpoints to isolate failures.
  • Guided fixes: Provide quick, safe commands to restart or repair components without manual digging.

Quick Start

Run a quick diagnostic: ct orchestrator status; ct api status; ct db check; ct thread list --all.

Frequently Asked Questions about ct-debug-skill

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose issues with claude-threads and the orchestrator?

Diagnose claude-threads and orchestrator issues by running health checks: ct orchestrator status, ct api status, ct db check, and ct thread list --all. These commands surface stuck threads, startup failures, and coordination problems across local development, CI pipelines, and production environments.

What should I do when threads get stuck or the orchestrator fails to start?

Inspect thread logs and orchestrator status using bash-based diagnostics to identify root causes—stuck threads, orphaned worktrees, or database inconsistencies. The Skill provides guided commands to restart or repair components safely without manual investigation.

Can I troubleshoot event delivery and database issues in claude-threads?

Yes. Filter and monitor events, inspect database consistency, and handle locks using allowed tools like Bash, Read, and Grep. This isolates undelivered events and database problems that prevent proper thread and agent coordination.

How do I find and fix orphaned worktrees and PR shepherd problems?

Use health checks and log inspection to locate orphaned worktrees and PR shepherd failures. The Skill executes targeted remediation workflows that rapidly isolate and repair coordination issues across your environment.

What's the fastest way to reduce debugging time for orchestrator and thread failures?

Run system-wide health checks that verify orchestrator, API, and database health to surface issues early. This eliminates manual digging by providing clear status and actionable diagnostics for rapid isolation and remediation.

Does this work for troubleshooting in production-like environments?

Yes. The Skill handles diagnostics and remediation for local development, CI pipelines, and production-like environments, covering stuck threads, startup failures, orphaned worktrees, undelivered events, and database inconsistencies across all deployment contexts.