96 lines
4.8 KiB
Markdown
96 lines
4.8 KiB
Markdown
# 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):
|
||
```powershell
|
||
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:
|
||
|
||
```powershell
|
||
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)
|
||
|
||
```powershell
|
||
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.
|