Real-time dashboard for Claude Code agents β monitor status, token usage, git branches, PRs, and containers
Like the Byakugan β the HyΕ«ga clan's kekkei genkai β byakugan sees through your entire development environment from a single screen.
While active, it monitors all running Claude Code processes in near-360Β° real-time vision. From chakra flow (token usage) to each process's inner state (thinking / executing / waiting), to intelligence from kilometers away (multiple repos, branches, PRs) β all gathered on one screen. Even tenketsu (Docker container status) never escapes its sight.
Click any row to instantly jump to the corresponding VSCode / Cursor window. macOS only.
ζ₯ζ¬θͺη README γ―γγ‘γ
- Developers working with multiple displays
- Developers who use VSCode or Cursor as their primary IDE, with multiple instances open simultaneously, each running a Claude Code agent in its own terminal
Real usage β multiple worktrees of the same repository grouped together:
Demo mode β all sensitive info replaced with dummy data (toggle with the Demo button):
Each Claude Code process appears as a row with:
- Project + Dir + Branch + PR columns
- Status: live Claude state β
thinking/tool_use/executing/waiting - Docker containers status (
π³ 3/4 api db redis) β opt-in viaBYAKUGAN_DOCKER=true - CPU / MEM / Uptime stats
- Column show/hide: click any column header to toggle visibility (persisted)
- Star: pin important processes to the top
- Drag & drop row reordering: drag rows to reorder, persisted in localStorage
- Recently opened projects: editor windows without an active Claude process, collapsible
- Token usage: 5-hour and weekly Claude API usage (e.g.
5h:32% (2h5m)[reset:02:00] wk:35%(2d13h)) - Working/idle counts: Live count of active and idle agents
- Demo mode: Replace all project info with dummy data for screenshots
- One-click IDE focus: Click any row to instantly activate the corresponding VSCode / Cursor window (rows with editor icon only)
- Selection highlight: Last clicked row retains highlight until another is selected
- Dark / light theme: Follows system preference
- SSE-based live updates: Refreshes every 2 seconds
- PR info caching:
gh pr viewis only called whenFETCH_HEADchanges (on push/pull/fetch) - Hot reload: Auto-reloads the UI when files in
public/change during development
- macOS (uses
ps,lsof) - Node.js 18+
- GitHub CLI (
gh) β for PR link detection - Git β for branch info
codeCLI (optional) β for "Open in VSCode" worktree feature (install via VSCode: Shell Command: Install 'code' command in PATH)
git clone https://github.com/litencatt/byakugan.git
cd byakugan
npm installnpm run devOpen http://localhost:3000 in your browser.
To use a custom port:
PORT=8080 npm run devnpm run build
npm start- Backend: Node.js + TypeScript + Express
- Frontend: Vanilla JavaScript (SSE client, no framework)
- Communication: Server-Sent Events (real-time push)
- Process info:
ps,lsof,git,ghCLI - Window focus: Swift binary (
focus-window) withosascript+open -afallback - Worktree open:
codeCLI
npm run build # Compile TypeScript
npm run dev # Development mode (tsx watch + hot reload)
npm start # Production mode (after build)
npm test # Run tests
npm run test:watch # Watch mode tests| Variable | Default | Description |
|---|---|---|
PORT |
3000 |
HTTP server port |
BYAKUGAN_POLL_INTERVAL |
2 |
SSE push interval & process data cache TTL (seconds) |
| Process monitoring | ||
BYAKUGAN_PROCESS_NAMES |
claude |
Comma-separated list of process names to monitor (e.g. claude,codex) |
BYAKUGAN_DOCKER |
(disabled) | Set true to enable Docker Compose container status detection |
| OAuth usage | ||
BYAKUGAN_OAUTH_FETCH |
true |
Set false to disable OAuth usage API calls (e.g. during persistent 429) |
BYAKUGAN_OAUTH_CACHE_TTL |
300 |
OAuth success response cache duration (seconds) |
BYAKUGAN_USAGE_CACHE_PATH |
~/.claude/plugins/byakugan/.usage-cache.json |
Disk cache path for OAuth usage API responses (survives server restarts) |
| Paths (advanced) | ||
BYAKUGAN_OAUTH_API_HOSTNAME |
api.anthropic.com |
OAuth API hostname |
BYAKUGAN_PROJECTS_DIR |
~/.claude/projects |
Claude projects directory path |
BYAKUGAN_CREDENTIALS_PATH |
~/.claude/.credentials.json |
OAuth credentials file path |
BYAKUGAN_VSCODE_STORAGE_PATH |
(macOS default) | Override VSCode global storage path |
BYAKUGAN_CURSOR_STORAGE_PATH |
(macOS default) | Override Cursor global storage path |
SSE stream β pushes full dashboard data every 2 seconds.
Returns a snapshot of all running Claude Code processes.
Response example:
{
"processes": [
{
"pid": 12345,
"projectName": "my-project",
"projectDir": "/Users/user/projects/my-project",
"status": "working",
"claudeStatus": "executing",
"cpuPercent": 15.2,
"memPercent": 8.5,
"currentTask": "Implement new feature for dashboard",
"gitBranch": "feat/new-feature",
"gitCommonDir": "/Users/user/projects/my-project/.git",
"modelName": "claude-sonnet-4-6",
"prUrl": "https://github.com/user/repo/pull/123",
"openFiles": ["src/server.ts", "src/types.ts"],
"editorApp": "vscode",
"containers": [
{ "service": "api", "name": "api-1", "state": "running", "status": "Up 2 hours" }
]
}
],
"editorWindows": [],
"totalWorking": 1,
"totalIdle": 2,
"usage": {
"totalInputTokens": 120000,
"totalOutputTokens": 45000,
"fiveHourPercent": 32,
"weeklyPercent": 35,
"fiveHourResetsAt": "2025-01-15T02:00:00Z",
"weeklyResetsAt": "2025-01-20T00:00:00Z"
},
"collectedAt": "2025-01-15T10:30:45.123Z"
}Focus the editor window associated with a Claude process.
{ "pid": 12345 }Focus an editor window not associated with a Claude process.
{ "projectDir": "/Users/user/projects/my-project", "app": "vscode" }Make sure Claude Code is running:
ps aux | grep claude- Ensure GitHub CLI (
gh) is installed and authenticated - The current branch must not be
mainormaster
- Make sure the editor is running
- Check macOS accessibility permissions in System Settings β Privacy & Security β Accessibility
MIT
Issues and pull requests are welcome!