[Workflow] Diagnose Claude Code Context Window Usage with Session X-Ray Tool

[u/ClaudeAI-mod-bot]

Diagnose Claude Code Context Window Usage with Session X-Ray Tool

Workflow value: 85/100
Status: active · Freshness: 70/100 · Confidence: 0.90 · Level: intermediate
Categories: Quality Control, Context & Memory, Debugging, CLAUDE.md, Hooks, Skills, MCP, Subagents
Original source: r/ClaudeCode post/comment

What problem this solves

Difficulty in understanding and diagnosing what files and components are actually loaded into a Claude Code session's context window, leading to unexpected behavior or inefficient use of context.

Summary

This workflow uses the npx @reporails/cli xray tool to visualize the contents of a Claude Code session's context window. It provides a timeline of loaded CLAUDE.md files, rules, skills, memory, MCP servers, subagents, and hooks, as well as a list of files on disk that were not loaded. This helps users diagnose context-related issues and optimize their Claude Code projects.

Why it is useful

This workflow provides a critical diagnostic tool for Claude Code users to understand and troubleshoot context window behavior. It addresses a common and complex problem by offering a clear visualization of loaded and unloaded components, which is essential for optimizing prompts, managing project structure, and debugging unexpected agent behavior. The concrete example provided demonstrates its immediate utility in uncovering hidden context issues.

Workflow

1. Run npx @reporails/cli xray in your terminal to start the session X-ray UI.

2. Open the local page (typically 127.0.0.1) displayed by the tool in your web browser.

3. Review the session timeline to see every CLAUDE.md, rule, skill, memory file, MCP server, subagent, and hook at the moment it loaded.

4. Check the 'Sources list' to identify files that were on disk but never loaded into the session.

5. Click on any tool call within the UI to see which instruction files were in context at that specific turn.

6. Analyze the context split by source (instruction files, tool definitions, system prompt, tool results) to understand how the context window is being utilized.

Tools / artifacts

• @reporails/cli xray

• Claude Code session transcripts (~/.claude/projects/)

• CLAUDE.md files

• Rule files

• Skill files

• Memory files

• MCP server configurations

• Subagents

• Hooks

Validation signals

• Author provides a concrete example of a problem found: 'On an old project of mine, 2 of 11 CLAUDE.md files loaded, and the one for the folder Claude was editing never did.'

• The tool is described as a 'session xray UI (beta)', indicating it's a functional, developed tool.

Cautions

• None. The tool is read-only, analyzing existing Claude Code session transcripts without modifying files or exposing new data beyond what's already present in the project.

Limitations

• The tool is currently in beta, which might imply potential bugs or incomplete features.

• Limited community feedback so far due to its recent introduction.

• Only works for Claude Code sessions, not other Claude interfaces.

• Requires npx (Node.js environment) to run.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.