claude-local-overview-display/README.md

Claude Overview

A small native Windows widget that shows your active Claude Code chats started in VS Code (running inside WSL) and their token usage. It docks to the bottom-right corner of a chosen monitor and toggles between two states:

• State 1 (minimized): a 44×44 arrow button (◤) in the bottom-right corner.
• State 2 (expanded): a borderless panel listing each active chat — project, last activity, token usage, model — with a per-session total in the footer.

Click the arrow to expand; click ▾ to minimize. The window is borderless, always-on-top, and has no taskbar entry.

How it works

Claude Code writes a transcript (.jsonl) per chat under ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl. Since you run Claude in WSL (Ubuntu), the app reads those files over the Windows share:

\\wsl.localhost\Ubuntu\home\philipp\.claude\projects

For each transcript it:

• keeps only chats with entrypoint = "claude-vscode" (VS Code),
• treats a chat as active if the file was written within activeMinutes (default 5),
• sums usage tokens (input / output / cache read / cache creation) across assistant messages.

Only recently-modified files are fully parsed, so the scan stays fast regardless of history size. It rescans every refreshSeconds (default 4).

Status states

Each chat shows one of three states, colour-coded by its status dot:

• working… (green) — Claude is generating or running an auto-approved tool.
• waiting for you / question for you (amber) — Claude finished its turn or posed a question.
• needs permission (red, e.g. allow Bash?) — Claude is blocked on a tool-permission prompt.

The permission state can't be read directly from the transcript (a pending tool call looks the same whether it's running or awaiting approval), so it's inferred: a tool call that isn't auto-approved by your permission settings and has sat without completing for pendingPermissionSeconds (default 8) is treated as a prompt. Auto-approval is checked against your ~/.claude/settings.json and the project's .claude/settings.json / settings.local.json permissions.allow rules — so an allowlisted long-running command (a build, a test run) stays working… instead of being mislabelled.

Requirements

• Windows 10/11 with WSL2 (you already run Claude in WSL).
• .NET SDK 8 on the Windows side (not in WSL — WPF is Windows-only):

  winget install Microsoft.DotNet.SDK.8
  

Build & run

From a Windows terminal (PowerShell or cmd), navigate to this folder via the WSL share and run it:

cd \\wsl.localhost\Ubuntu\home\philipp\git\claude-local-overview-display
dotnet run -c Release

…or just double-click run-on-windows.cmd from Explorer.

If building directly on the \\wsl.localhost UNC path misbehaves, copy the folder to a local path (e.g. C:\Tools\ClaudeOverview) and build there. It will still read the WSL transcripts over the share.

A standalone exe (optional)

dotnet publish -c Release -r win-x64 --self-contained false -o publish

Then run publish\ClaudeOverview.exe. To launch at login, drop a shortcut to it in shell:startup.

Configuration — config.json

Lives next to the exe; edit and restart.

Key	Default	Meaning
wslDistro	Ubuntu	WSL distro name (wsl -l -q to list).
linuxHome	/home/philipp	Your Linux home dir.
projectsPathOverride	""	Full Windows path to .claude/projects; overrides the two above.
activeMinutes	5	A chat is "active" if written within this many minutes.
refreshSeconds	4	Rescan interval.
monitorIndex	-1	Which monitor to dock to. -1 = last screen (typical side monitor), 0 = primary, 1 = second…
edgeMargin	12	Gap (px) from the corner.
onlyVsCode	true	Only show VS Code chats. Set false to include CLI chats too.
startMinimized	true	Start in State 1.

Project layout

File	Purpose
ClaudeOverview.csproj / app.manifest	WPF app targeting net8.0-windows, per-monitor DPI aware.
App.xaml	Theme/brushes and shared styles.
MainWindow.xaml / .cs	The widget: both states, corner docking, refresh timer.
Models/ClaudeSession.cs	One parsed chat + usage totals and display helpers.
Services/SessionScanner.cs	Enumerates and parses transcripts.
Services/AppConfig.cs	Loads config.json.

Troubleshooting

• "Projects path not found" in the panel: WSL may be stopped — open a WSL terminal once, or check wslDistro / linuxHome in config.json.
• Nothing listed: no VS Code chat has been touched in the last activeMinutes. Start/continue a chat in VS Code, or raise activeMinutes.
• Wrong monitor / corner: adjust monitorIndex. You can also drag the expanded panel by its header.