Claude Code command show markdown files read in current session

ctx.md

name	description
ctx	Show markdown files read in current session

Context Status

Show markdown file read coverage in current session.

Options

• --all: Show all markdown files in repo (unread files show 0%). Uses --depth 3 and --max 30 by default
• --depth N: Directory traversal depth (only with --all, default: 3)
• --max N: Max files to display (only with --all, default: 30)

Examples

/ctx                            # Only show read files
/ctx --all                      # Show all md files (depth 3, max 30)
/ctx --all --depth 5 --max 50   # Custom depth and max

Instructions

Step 1: Parse arguments

Parse user arguments:

• show_all: false (set true if --all present)
• max_depth: 3 (only used when show_all = true)
• max_files: 30 (only used when show_all = true)

Step 2: Locate the session transcript

1. Get the current working directory (e.g., /Users/kk/Documents/main/workspace)
2. Convert to Claude projects path: replace / with -, prepend -
   • Example: /Users/kk/Documents/main/workspace → -Users-kk-Documents-main-workspace
3. Session directory: ~/.claude/projects/{converted-path}/
4. Find the current session JSONL file:
   • List all .jsonl files sorted by modification time (newest first)
   • The current session is typically the most recently modified file

Step 3: Parse Read tool calls

JSONL line structure:

• {message: {content: [{type: "tool_use", name: "Read", input: {file_path, offset?, limit?}}]}}
• Skip lines without tool_use content

1. Parse the JSONL file and extract all Read tool calls where file_path ends with .md
2. For each markdown file read:
   • Get the file path
   • Get offset and limit (if specified)
   • If no offset: default to line 1
   • If no limit: treat as full file (get actual line count from filesystem)
   • Calculate which lines were read
3. If a file was read multiple times with different ranges, merge them.

Step 4: Collect files to display

Default mode (show_all = false):

• Only show files that were read in Step 3

All mode (show_all = true):

• Scan repo root for all .md files up to max_depth levels
• Exclude: node_modules/, .git/, vendor/, .cache/, .debug/, .log/, venv/, __pycache__/
• Mark unread files as 0% coverage
• Limit to max_files total (keep all read files first, fill rest with unread)

Step 5: Output

📄 Markdown Files Read (3/15 files)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

workspace/
├── CLAUDE.md          [████████] L1-139/139  (100%)
├── README.md          [████████] L1-84/84    (100%)
├── docs/
│   ├── guide.md       [░░░░░░░░] -           (0%)
│   └── api.md         [██░░░░░░] L1-20/100   (20%)
└── commands/
    └── ctx.md         [████████] L1-60/60    (100%)

Where:

• Title: (read/total files) in --all mode, (N files) in default mode
• [████████] = 100% read
• [░░░░░░░░] = 0% (unread, only in --all mode)
• [██░░░░░░] = partial read, heatmap shows actual line positions
• - = no line info (unread file)
• Line range shows min-max of all read lines (e.g., read L1-10 + L50-60 → L1-60)

Heatmap calculation:

• Divide file into 8 equal segments (by line count)
• Each segment: █ if any line in that range was read, ░ otherwise
• Example: 80-line file read L1-20 → first 2 segments covered → [██░░░░░░]

Notes

• Keep output concise - this goes into context
• Tree structure groups files by directory
• Read files always appear before unread files within same directory
• Paths are relative to repo root