# Introspection

> Test and verify Claude Code behaviour — hooks, instructions, CLAUDE.md rules, tool usage patterns — using a headless subprocess harness. Use when building integration tests, verifying hook execution, or validating Claude Code configuration end-to-end.

- Skill: `codethread/introspection` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add codethread/introspection`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codethread/introspection/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: codethread (https://skillmd.com/u/codethread)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/codethread/introspection

---


# Introspection

## Variables

### Commands

- `HEADLESS_CLAUDE_CMD`: `claude -p`

Test Claude Code behaviour by spawning headless `$HEADLESS_CLAUDE_CMD` subprocesses and inspecting the results.

## When to Use

- Verifying hooks fire and produce expected side effects
- Confirming CLAUDE.md rules influence model behaviour
- Testing skill triggering and tool-call patterns
- Running a lightweight integration suite against Claude Code configuration

## Reference Map

Open the reference that matches the task:

- `references/headless-test-harness.md` for environment setup, CLI flags, output parsing, and verification strategies

## Key Rules

- **Always strip `CLAUDECODE` from the subprocess env** — nested Claude Code refuses to run otherwise
- **Use `--model haiku`** to keep cost low (~$0.01-0.03 per invocation)
- **Set `--max-turns` tight** — haiku needs ~3-4 turns for read+edit tasks
- **PostToolUse hooks are silent in the stream** — verify them by checking side effects, not stream events
- `--verbose` is required when using `--output-format stream-json`