peekctx

See what Claude sees

A TUI for inspecting Claude Code's context — see exactly what files Claude has loaded, detect stale reads, catch disk drift, and understand your AI pair programmer's view of your codebase.

---

Demo

demo-feb1.mov

Animated gradient header, real-time context tracking, and full theme customization

---

Why peekctx?

When working with Claude Code, you might wonder:

• "Does Claude actually see my latest changes?" — peekctx detects disk drift
• "Is Claude's context getting stale?" — Track files read before compaction
• "How much context is Claude using?" — Visual token usage bar with compaction estimates
• "What files does Claude have loaded?" — Full file tree with token counts

peekctx gives you complete visibility into Claude's context window.

---

Features

Context Visibility

• Token usage bar — Color-coded progress showing context usage with compaction estimates
• File tree view — All loaded files organized by directory with token counts
• Function extraction — See individual functions/types Claude has loaded (Go, JS/TS, Python, Rust)

Smart Detection

• Disk drift detection — Flags files that changed on disk since Claude read them (⚠ red)
• Stale file detection — Highlights files only known from pre-compaction summary (◐ muted)
• Health summary — Quick status with actionable recommendations

File Context

• Interaction timeline — See every read/write/edit operation on a file
• Conversation context — View what you asked and what Claude responded for each file
• Full message history — Search across all conversation mentioning a file

Beautiful UI

• 8 built-in themes — Peekctx (default), Grayscale, Ocean, Sunset, Forest, Cyberpunk, ROYGBIV
• Custom themes — Define your own colors and gradients
• Animated gradients — Smooth color transitions on the brain logo and context bar
• Live watch mode — Auto-refresh as Claude works

---

Installation

From Source

# Clone the repository
git clone https://github.com/jeremyengland/peekctx.git
cd peekctx

# Build
go build -o peekctx

# Move to PATH (optional)
sudo mv peekctx /usr/local/bin/

Requirements

• Go 1.21+
• macOS or Linux
• Claude Code CLI installed (~/.claude/ directory must exist)

---

Usage

# Inspect context for current directory
peekctx

# Live watch mode (auto-refresh every 2s)
peekctx --watch

# Show help
peekctx --help

---

Navigation

Global Keys

Key	Action
q / Ctrl+C	Quit
r	Refresh data
,	Open preferences

List View (Session Selection)

Key	Action
j / k / ↑ / ↓	Navigate sessions
Enter	Select session

Detail View (Context Inspector)

Key	Action
j / k / ↑ / ↓	Move cursor
Enter / Space	Expand/collapse
→	Expand node
←	Collapse node
i	File info (interaction timeline)
t	Toggle sort (recency/path/status/tokens)
f	Toggle filter (all/drifted/stale/problems)
c	Collapse all
e	Expand all
y	Copy file path
o	Open in editor
/	Search files
h / ?	Show all keybindings
Esc	Go back

File Context View

Key	Action
j / k / ↑ / ↓	Scroll
Esc	Go back

---

Status Indicators

Icon	Color	Meaning
⚠	Red	Drifted — File changed on disk since Claude read it
◐	Muted	Stale — Read before compaction, only in summary
●	Green	Healthy — No issues
●	Yellow	Warning — 1 issue (high usage or drift)
●	Red	Needs Attention — Multiple issues

---

Themes

Access themes via , (preferences):

Theme	Description
Peekctx	Default vibrant pink/violet
Grayscale	Clean monochrome
Ocean	Deep blue and teal
Sunset	Warm orange and magenta
Forest	Lush greens
Cyberpunk	Neon cyan and magenta
ROYGBIV	Full rainbow spectrum
Custom	Define your own 8-color palette + gradient

Custom Theme

Edit ~/.claude/peekctx/config.json:

{
  "theme": "custom",
  "customTheme": {
    "primary": "#FF1493",
    "secondary": "#7C3AED",
    "text": "#FFFFFF",
    "muted": "#6B7280",
    "green": "#22C55E",
    "yellow": "#EAB308",
    "red": "#EF4444",
    "brainGradient": ["#7C3AED", "#FF1493", "#FF6B6B"]
  }
}

---

Editor Integration

Set your preferred editor in preferences:

Editor	Command
Terminal	Uses $EDITOR env var (vim, nano, etc.)
VS Code	code
Cursor	cursor

Press o on any file to open it directly.

---

How It Works

peekctx reads Claude Code's session data from:

~/.claude/projects/[encoded-path]/[session-id].jsonl

It parses the JSONL to extract:

• Tool calls — Read, Write, Edit operations
• File contents — What Claude actually saw
• Token usage — From API responses
• Timestamps — When each operation occurred

Drift Detection

peekctx hashes file contents when Claude reads them, then compares against current disk state. If they differ, the file is marked as drifted.

Stale Detection

After context compaction, Claude only knows files from the summary. Files read before the last compaction are marked stale — Claude may not remember the actual contents.

---

Development

# Run in development
go run main.go

# Run with watch mode
go run main.go --watch

# Build
go build

# Run tests
go test ./...

Project Structure

peekctx/
├── main.go                 # Entry point
├── pkg/
│   ├── claude/             # Session parsing
│   │   ├── parse.go        # JSONL parsing
│   │   ├── session.go      # Session discovery
│   │   └── symbols.go      # Code symbol extraction
│   ├── config/             # User preferences
│   ├── gui/                # TUI views
│   │   ├── app.go          # Router
│   │   ├── list.go         # Session list
│   │   ├── detail.go       # Context detail
│   │   ├── filecontext.go  # File interaction view
│   │   ├── preferences.go  # Settings
│   │   ├── theme/          # Color themes
│   │   └── components/     # Reusable UI
│   ├── clipboard/          # Copy support
│   └── editor/             # Editor launching
└── assets/                 # Demo videos, brain ASCII

---

Tech Stack

• Go — Fast, simple, compiles to single binary
• Bubbletea — Elm-architecture TUI framework
• Lipgloss — CSS-like terminal styling
• Bubbles — TUI components (viewport, text input)

---

Contributing

Contributions welcome! Please feel free to submit a Pull Request.

---

License

MIT License — see LICENSE for details.

---

_{Built with Claude Code + peekctx (yes, we used it to build itself)}