Skip to content

Commit ae9da12

Browse files
yepzdkclaude
yepzdk
and
claude
committed
Initial implementation of Claude Sessions Monitor
- Session discovery and JSONL parsing - Live dashboard with auto-refresh - List mode (-l) and JSON output (-l -json) - Status detection: Working, Needs Input, Waiting, Idle - Cross-platform build support via Makefile Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
0 parents  commit ae9da12

File tree

9 files changed

+926
-0
lines changed

9 files changed

+926
-0
lines changed

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Binary
2+
csm
3+
4+
# Build artifacts
5+
dist/

‎Makefile‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
.PHONY: build build-all install clean
2+
3+
VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
4+
LDFLAGS := -ldflags "-X main.version=$(VERSION)"
5+
6+
# Build for current platform
7+
build:
8+
go build $(LDFLAGS) -o csm .
9+
10+
# Build for all platforms
11+
build-all: clean
12+
@mkdir -p dist
13+
GOOS=darwin GOARCH=amd64 go build $(LDFLAGS) -o dist/csm-darwin-amd64 .
14+
GOOS=darwin GOARCH=arm64 go build $(LDFLAGS) -o dist/csm-darwin-arm64 .
15+
GOOS=linux GOARCH=amd64 go build $(LDFLAGS) -o dist/csm-linux-amd64 .
16+
GOOS=linux GOARCH=arm64 go build $(LDFLAGS) -o dist/csm-linux-arm64 .
17+
18+
# Install to ~/.local/bin
19+
install: build
20+
@mkdir -p $(HOME)/.local/bin
21+
cp csm $(HOME)/.local/bin/csm
22+
@echo "Installed to $(HOME)/.local/bin/csm"
23+
24+
# Clean build artifacts
25+
clean:
26+
rm -f csm
27+
rm -rf dist

‎PROMPT.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Claude Sessions Monitor - Project Kickoff
2+
3+
## Overview
4+
5+
Build a CLI tool in Go called `csm` (Claude Sessions Monitor) that monitors Claude Code sessions and displays their status in the terminal. The tool should have zero external dependencies (standard library only) for easy distribution as a single binary.
6+
7+
## Problem Being Solved
8+
9+
When running multiple Claude Code sessions in different terminal tabs/windows, it's hard to keep track of which sessions are:
10+
- Actively working
11+
- Waiting for user input/approval
12+
- Idle or finished
13+
14+
This tool watches `~/.claude/projects/` and provides a live dashboard showing all sessions and their current status.
15+
16+
## Core Features
17+
18+
### 1. Session Discovery
19+
- Scan `~/.claude/projects/` directory
20+
- Each subdirectory is a project (URL-encoded path like `%2Fhome%2Fuser%2Fproject`)
21+
- Find the most recent `.jsonl` log file in each project
22+
- Parse JSONL to determine session state
23+
24+
### 2. Status Detection
25+
Parse the JSONL log entries to determine status:
26+
27+
| Status | Condition |
28+
|--------|-----------|
29+
| **Working** | Recent assistant message, still streaming/processing |
30+
| **Needs Approval** | Last entry is assistant with `tool_use`, waiting for user to approve |
31+
| **Waiting** | Turn ended, waiting for user's next prompt |
32+
| **Idle** | No activity for 5+ minutes |
33+
34+
Log entry types to look for:
35+
- `type: "assistant"` with `content[].type: "tool_use"` → tool requested
36+
- `type: "user"` with `content[].type: "tool_result"` → tool approved/executed
37+
- `type: "system"` with `turn_duration` → turn completed
38+
- Timestamps for activity tracking
39+
40+
### 3. CLI Modes
41+
42+
```
43+
csm # Live view (default) - auto-updating dashboard
44+
csm -l # List once and exit
45+
csm -l -json # List as JSON
46+
csm -v # Version
47+
csm -interval 5s # Custom refresh interval (default 2s)
48+
```
49+
50+
### 4. Live View Display
51+
52+
```
53+
🤖 Claude Code Sessions
54+
55+
● Working: 2 ⚠ Needs Input: 1 ◉ Waiting: 0 ○ Idle: 3
56+
57+
STATUS PROJECT LAST ACTIVITY CURRENT TASK
58+
────────────────────────────────────────────────────────────────────────────────
59+
● Working myorg/api-server 5s ago Implementing auth middleware...
60+
● Working myorg/frontend 12s ago Using: Edit
61+
⚠ Needs Input personal/side-project 45s ago Using: Bash
62+
○ Idle work/legacy-app 15m ago -
63+
64+
Press Ctrl+C to quit
65+
```
66+
67+
Use ANSI colors:
68+
- Green for Working
69+
- Yellow/Orange for Needs Input
70+
- Blue for Waiting
71+
- Gray for Idle
72+
73+
### 5. List Mode Output
74+
75+
```
76+
STATUS PROJECT LAST ACTIVITY TASK
77+
────────────────────────────────────────────────────────────────────────────────
78+
● Working myorg/api-server 5s ago Implementing auth...
79+
⚠ Needs Input personal/side-project 45s ago Using: Bash
80+
```
81+
82+
### 6. JSON Output
83+
84+
```json
85+
[
86+
{"project": "myorg/api-server", "status": "Working", "last_activity": "2024-01-15T10:30:00Z", "task": "Implementing..."},
87+
{"project": "personal/side-project", "status": "Needs Approval", "last_activity": "2024-01-15T10:29:15Z", "task": "Using: Bash"}
88+
]
89+
```
90+
91+
## Project Structure
92+
93+
```
94+
claude-sessions-monitor/
95+
├── main.go # CLI entry point, flag parsing
96+
├── internal/
97+
│ ├── session/
98+
│ │ └── session.go # Session discovery and JSONL parsing
99+
│ ├── watcher/
100+
│ │ └── watcher.go # File system watching for changes
101+
│ └── ui/
102+
│ └── ui.go # Terminal rendering (ANSI)
103+
├── go.mod
104+
├── README.md
105+
├── CHANGELOG.md
106+
└── Makefile # Build targets for multiple platforms
107+
```
108+
109+
## Technical Requirements
110+
111+
1. **Zero external dependencies** - use only Go standard library
112+
2. **Cross-platform** - must work on macOS and Linux
113+
3. **Single binary** - easy to distribute
114+
4. **Efficient** - poll filesystem changes, don't hammer CPU
115+
5. **Graceful** - handle Ctrl+C cleanly, restore cursor
116+
117+
## Build & Distribution
118+
119+
Makefile should support:
120+
```makefile
121+
build: # Build for current platform
122+
build-all: # Build for linux/darwin, amd64/arm64
123+
install: # Install to ~/.local/bin
124+
```
125+
126+
## JSONL Log Format Reference
127+
128+
Each line in the log file is a JSON object:
129+
130+
```json
131+
{"type": "user", "message": {"role": "user", "content": [{"type": "text", "text": "..."}]}, "timestamp": "..."}
132+
{"type": "assistant", "message": {"role": "assistant", "content": [{"type": "text", "text": "..."}]}, "timestamp": "..."}
133+
{"type": "assistant", "message": {"role": "assistant", "content": [{"type": "tool_use", "name": "Edit", "id": "..."}]}, "timestamp": "..."}
134+
{"type": "user", "message": {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "..."}]}, "timestamp": "..."}
135+
{"type": "system", "message": {"turn_duration": 5.2}, "timestamp": "..."}
136+
```
137+
138+
## Getting Started
139+
140+
1. Initialize the Go module
141+
2. Create the directory structure
142+
3. Implement session discovery first (can test with -l flag)
143+
4. Add the watcher for live updates
144+
5. Implement the terminal UI
145+
6. Add Makefile for builds
146+
7. Write README with installation instructions
147+
148+
Start by exploring `~/.claude/projects/` to understand the actual structure, then implement session parsing.

‎README.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Claude Sessions Monitor (csm)
2+
3+
A lightweight CLI tool to monitor your Claude Code sessions across multiple projects.
4+
5+
## Features
6+
7+
- **Live dashboard** showing all active Claude Code sessions
8+
- **Status indicators**: Working, Needs Input, Waiting, Idle
9+
- **Zero dependencies** - single binary, easy to install
10+
- **Cross-platform** - macOS and Linux
11+
12+
## Installation
13+
14+
### From releases
15+
16+
Download the latest binary from [Releases](https://github.com/itk-dev/claude-sessions-monitor/releases) and add to your PATH.
17+
18+
### Build from source
19+
20+
```bash
21+
git clone https://github.com/itk-dev/claude-sessions-monitor.git
22+
cd claude-sessions-monitor
23+
make install
24+
```
25+
26+
## Usage
27+
28+
```bash
29+
# Live view (default)
30+
csm
31+
32+
# List sessions once
33+
csm -l
34+
35+
# Output as JSON
36+
csm -l -json
37+
38+
# Custom refresh interval
39+
csm -interval 5s
40+
41+
# Show version
42+
csm -v
43+
```
44+
45+
## Status Types
46+
47+
| Symbol | Status | Description |
48+
|--------|--------|-------------|
49+
| ● | Working | Session is actively processing |
50+
| ⚠ | Needs Input | Waiting for user to approve a tool use |
51+
| ◉ | Waiting | Turn completed, waiting for next prompt |
52+
| ○ | Idle | No activity for 5+ minutes |
53+
54+
## Screenshot
55+
56+
```
57+
🤖 Claude Code Sessions
58+
59+
● Working: 2 ⚠ Needs Input: 1 ◉ Waiting: 0 ○ Idle: 1
60+
61+
STATUS PROJECT LAST ACTIVITY CURRENT TASK
62+
────────────────────────────────────────────────────────────────────────────────
63+
● Working myorg/api-server 5s ago Implementing auth middleware...
64+
⚠ Needs Input personal/side-project 45s ago Using: Bash
65+
○ Idle work/legacy-app 15m ago -
66+
67+
Press Ctrl+C to quit
68+
```
69+
70+
## Building
71+
72+
```bash
73+
# Build for current platform
74+
make build
75+
76+
# Build for all platforms (darwin/linux, amd64/arm64)
77+
make build-all
78+
79+
# Clean build artifacts
80+
make clean
81+
```
82+
83+
## How it works
84+
85+
The tool monitors `~/.claude/projects/` where Claude Code stores session logs. It parses the JSONL log files to determine each session's current state based on the most recent entries.
86+
87+
## License
88+
89+
MIT

‎go.mod‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module github.com/itk-dev/claude-sessions-monitor
2+
3+
go 1.25.6

0 commit comments

Comments
 (0)