What is headless mode in Claude Code?

Headless mode allows you to run Claude Code non-interactively using the -p flag, which is ideal for automation, scripting, and CI/CD pipelines.

Can I use this for the Gemini CLI?

Yes, the debug-headless skill supports debugging workflows for both Claude Code and the Gemini CLI.

What is the difference between abridged and full transcripts?

Full transcripts include all tool execution results, while abridged transcripts provide a compact view of the conversation and logic without verbose tool outputs.

How does this skill help with hook verification?

It generates transcripts that explicitly display 'Hook: EventName' markers and exit codes, making it easy to identify which hooks fired and where they failed.

Where are the session logs stored?

Logs are typically stored as .jsonl files in the ~/.claude/projects/ directory, organized by project-specific path hashes.

Headless AI CLI Debugger

Name: Headless AI CLI Debugger
Author: nicsuzor

bynicsuzor

0•

Analytics & Monitoring

Debugs Claude Code and Gemini CLI sessions in headless mode by capturing outputs and generating human-readable transcripts.

The Headless AI CLI Debugger is a specialized utility designed for developers running AI-powered command-line tools in automated or non-interactive environments. It provides a structured workflow for capturing raw JSONL session logs, locating specific project session files, and transforming them into readable Markdown transcripts. This tool is essential for verifying hook execution, analyzing subagent behavior, and troubleshooting failures in headless pipelines where interactive debugging is not possible, allowing for deep post-mortem analysis of AI agent performance.

Key Features

01Generation of abridged and full Markdown transcripts from raw JSONL logs

02Visual indicators for tool success, failures, and parallel execution turns

03Detailed tracking of hook execution status and subagent triggers

04Automated capture of non-interactive Claude Code and Gemini CLI output

05Advanced session file discovery based on project path or prompt content

060 GitHub stars

Use Cases

01Troubleshooting failed automated CI/CD pipelines involving AI code agents

02Auditing complex AI workflows to verify which hooks and axioms were triggered

03Analyzing subagent performance and parallel tool execution in headless environments

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add nicsuzor/academicops debug-headless

For use in Claude.ai and ChatGPT

Download Skill