claude-scope 0.8.15 → 0.8.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +223 -82
  2. package/dist/claude-scope.cjs +1207 -401
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,37 +1,77 @@
1
- # claude-scope
1
+ <div align="center">
2
2
 
3
- Claude Code plugin for session status and analytics.
3
+ <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/typescript/typescript-original.svg" alt="TypeScript" width="80" height="80"/>
4
4
 
5
- **Requirements:**
6
- - Node.js 18 or higher
5
+ # claude-scope
7
6
 
8
- ## Installation
7
+ ### Beautiful, customizable statusline for Claude Code CLI
9
8
 
10
- ### Via npx (recommended)
9
+ [![npm version](https://badge.fury.io/js/claude-scope.svg)](https://www.npmjs.com/package/claude-scope)
10
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
11
+ [![Node.js Version](https://img.shields.io/node/v/claude-scope.svg)](https://github.com/YuriNachos/claude-scope)
12
+ [![GitHub Stars](https://img.shields.io/github/stars/YuriNachos/claude-scope?style=social)](https://github.com/YuriNachos/claude-scope)
13
+ [![codecov](https://codecov.io/gh/YuriNachos/claude-scope/branch/main/graph/badge.svg)](https://codecov.io/gh/YuriNachos/claude-scope)
11
14
 
12
- No installation required:
15
+ **Features** · [Installation](#-quick-start) · [Configuration](#-ai-powered-customization) · [Widgets](#-available-widgets) · [Themes](#-themes)
13
16
 
14
- ```bash
15
- npx claude-scope@latest
16
- ```
17
+ </div>
17
18
 
18
- ### Via npm globally
19
+ ---
19
20
 
20
- ```bash
21
- npm install -g claude-scope
21
+ <p align="center">
22
+ <i>Real-time session analytics in your terminal — zero runtime dependencies, 14 widgets, 17 themes</i>
23
+ </p>
24
+
25
+ ---
26
+
27
+ ## What is it?
28
+
29
+ **claude-scope** is a CLI plugin for [Claude Code](https://claude.ai/code) that displays real-time session information directly in your statusline. Track your context usage, session cost, git status, active tools, and more — all with beautiful customizable themes.
30
+
31
+ - **Zero runtime dependencies** — pure TypeScript, native Node.js only
32
+ - **14 customizable widgets** — model, context, cost, git, docker, and more
33
+ - **17 built-in themes** — from Dracula to Nord to Cyberpunk
34
+ - **12 display styles** — balanced, playful, compact, verbose, technical...
35
+ - **AI-friendly configuration** — just ask Claude to customize it!
36
+
37
+ ---
38
+
39
+ ## Preview
40
+
41
+ See how claude-scope looks with different themes:
42
+
43
+ **Dracula Theme** (default)
44
+ ```
45
+ Claude Opus 4.5 | 67% [████████] | +127/-42 | $1.24 | 2h 15m
46
+ main [+127 -42] | v0.8.16 | 💾 45.2k | 📄 1 📜 2 🔌 3 🪝 2
47
+ ⚡ Nuxt (running) | 🐳 3/5 🟢 | Edits: 8 | Bash: 3 | Read: 12
22
48
  ```
23
49
 
24
- ### Via bun
50
+ **Tokyo Night Theme**
51
+ ```
52
+ Claude Opus 4.5 | 67% [████████] | +127/-42 | $1.24 | 2h 15m
53
+ main [+127 -42] | v0.8.16 | 💾 45.2k | 📄 1 📜 2 🔌 3 🪝 2
54
+ ⚡ Nuxt (running) | 🐳 3/5 🟢 | Edits: 8 | Bash: 3 | Read: 12
55
+ ```
25
56
 
26
- ```bash
27
- bunx claude-scope@latest
57
+ **Nord Theme**
58
+ ```
59
+ Claude Opus 4.5 | 67% [████████] | +127/-42 | $1.24 | 2h 15m
60
+ main [+127 -42] | v0.8.16 | 💾 45.2k | 📄 1 📜 2 🔌 3 🪝 2
61
+ ⚡ Nuxt (running) | 🐳 3/5 🟢 | Edits: 8 | Bash: 3 | Read: 12
28
62
  ```
29
63
 
30
- ## Configuration
64
+ ---
31
65
 
32
- Add to your `~/.claude/settings.json`:
66
+ ## Quick Start
33
67
 
34
- ```json
68
+ Get up and running in 30 seconds:
69
+
70
+ ```bash
71
+ # 1. Install via npx (no installation required)
72
+ npx -y claude-scope@latest
73
+
74
+ # 2. Add to your ~/.claude/settings.json
35
75
  {
36
76
  "statusLine": {
37
77
  "type": "command",
@@ -39,95 +79,196 @@ Add to your `~/.claude/settings.json`:
39
79
  "padding": 0
40
80
  }
41
81
  }
82
+
83
+ # 3. Restart Claude Code — you're done! 🎉
42
84
  ```
43
85
 
44
- Or for global install:
86
+ After the first run, a default config is automatically created at `~/.claude-scope/config.json` with:
87
+ - **Layout**: `rich` (3 lines)
88
+ - **Style**: `balanced`
89
+ - **Theme**: `dracula`
90
+
91
+ ---
92
+
93
+ ## 🤖 AI-Powered Customization
94
+
95
+ **claude-scope is built to work with AI!** Simply ask Claude to customize it:
96
+
97
+ ```
98
+ ➕ "Add the docker widget to the third line"
99
+ 🎨 "Switch theme to nord"
100
+ 😄 "Make it more playful"
101
+ 🎯 "Show only model and context"
102
+ ```
103
+
104
+ **Example dialogue:**
105
+
106
+ > **User:** Add poker widget and make everything playful
107
+ >
108
+ > **Claude:** Sure! Adding poker widget and changing styles to playful...
109
+ >
110
+ > ✅ Done! Your statusline now shows poker hands with emojis.
111
+
112
+ Claude will automatically modify `~/.claude-scope/config.json` — changes take effect instantly.
113
+
114
+ **How it works:**
115
+ - Config contains `$aiDocs` field linking to [AI-CONFIG-GUIDE](AI-CONFIG-GUIDE.md)
116
+ - AI understands all 14 widgets, 12 styles, and 17 themes
117
+ - Just say what you want — no manual editing needed
118
+
119
+ ---
120
+
121
+ ## Available Widgets
122
+
123
+ | Widget | Description | Balanced | Playful |
124
+ |--------|-------------|----------|---------|
125
+ | **model** | Current Claude model | `Claude Opus 4.5` | `🤖 Opus 4.5` |
126
+ | **context** | Context usage with progress bar | `45% [████████░░░░░░░░░]` | `📊 45% [████████░░░░░░░░░]` |
127
+ | **cost** | Session cost in USD | `$0.42` | `💰 $0.42` |
128
+ | **duration** | Session duration | `1h 15m 30s` | `⌛ 1h 15m` |
129
+ | **lines** | Lines added/removed | `+42/-18` | `➕42 ➖18` |
130
+ | **git** | Git branch and changes | `main [+42 -18]` | `🔀 main ⬆42 ⬇18` |
131
+ | **git-tag** | Latest git tag | `v0.8.16` | `🏷️ v0.8.16` |
132
+ | **config-count** | Config file counts | `📄 1 CLAUDE.md │ 📜 2 rules │ 🔌 3 MCPs` | — |
133
+ | **cache-metrics** | Cache statistics | `💾 35.0k cache` | `💾 35.0k cache` |
134
+ | **active-tools** | Active tools tracking | `Edits: 5 │ Bash: 3 │ Read: 2` | `✏️ Edit 📖 Read 🐚 Bash` |
135
+ | **dev-server** | Dev server status | `⚡ Nuxt (running)` | `🏃 Nuxt` |
136
+ | **docker** | Docker containers | `Docker: 3/5 🟢` | `🐳 Docker: 3/5 🟢` |
137
+ | **poker** | Poker hands (easter egg) | `Hand: A♠ K♠ │ One Pair!` | `🃏 A♠️ K♠️ │ One Pair!` |
138
+
139
+ ### Layout Presets
140
+
141
+ | Preset | Lines | Widgets |
142
+ |--------|-------|---------|
143
+ | **Rich** (default) | 3 | Line 0: model, context, lines, cost, duration<br>Line 1: git, git-tag, cache-metrics, config-count<br>Line 2: dev-server, docker, active-tools |
144
+ | **Balanced** | 2 | Line 0: model, context, lines, cost, duration<br>Line 1: git, git-tag, cache-metrics, config-count |
145
+ | **Compact** | 1 | Line 0: model, context, cost, git, duration |
146
+
147
+ ---
148
+
149
+ ## Themes
150
+
151
+ **Built-in themes** — from classic to futuristic:
152
+
153
+ | Theme | Style | Colors |
154
+ |-------|-------|--------|
155
+ | `dracula` | Popular | Purple, pink, green |
156
+ | `tokyo-night` | Modern | Blue, yellow, green |
157
+ | `nord` | Cool | Arctic blues |
158
+ | `monokai` | Vibrant | **DEFAULT** — bright accents |
159
+ | `catppuccin-mocha` | Pastel | Soft dreamy colors |
160
+ | `github-dark-dimmed` | Standard | GitHub's official dark |
161
+ | `vscode-dark-plus` | Standard | VSCode's default |
162
+ | `one-dark-pro` | IDE | Atom's iconic theme |
163
+ | `solarized-dark` | Classic | Precise CIELAB lightness |
164
+ | `rose-pine` | Pastel | Rose/violet themed |
165
+ | `cyberpunk-neon` | Vibrant | Cyberpunk 2077 neon |
166
+ | `professional-blue` | Professional | Business-oriented blue |
167
+ | `gray` | Minimal | Neutral gray, minimal |
168
+ | `muted-gray` | Muted | Very subtle grays |
169
+ | `slate-blue` | Muted | Calm blue-grays |
170
+ | `dusty-sage` | Muted | Earthy greens |
171
+ | `semantic-classic` | Intuitive | Industry-standard colors |
172
+
173
+ ---
174
+
175
+ ## Configuration
176
+
177
+ ### Quick Config
178
+
179
+ Interactive configuration menu:
180
+
181
+ ```bash
182
+ claude-scope quick-config
183
+ ```
184
+
185
+ Choose from:
186
+ - **Layout**: Rich (3 lines), Balanced (2 lines), Compact (1 line)
187
+ - **Theme**: 17 themes with live preview
188
+ - **Style**: balanced, playful, compact, verbose, technical...
189
+
190
+ ### Manual Configuration
191
+
192
+ Edit `~/.claude-scope/config.json` directly:
45
193
 
46
194
  ```json
47
195
  {
48
- "statusLine": {
49
- "type": "command",
50
- "command": "claude-scope",
51
- "padding": 0
196
+ "version": "1.0.0",
197
+ "$aiDocs": "https://github.com/YuriNachos/claude-scope/blob/main/AI-CONFIG-GUIDE.md",
198
+ "lines": {
199
+ "0": [
200
+ { "id": "model", "style": "balanced", "colors": { "name": "\\u001b[38;2;189;147;229m" } },
201
+ { "id": "context", "style": "balanced", "colors": { "low": "...", "medium": "...", "high": "..." } }
202
+ ]
52
203
  }
53
204
  }
54
205
  ```
55
206
 
56
- ## Usage
207
+ See [AI-CONFIG-GUIDE](AI-CONFIG-GUIDE.md) for complete configuration reference.
57
208
 
58
- Once configured, claude-scope displays real-time session information in your statusline including:
59
- - Git branch and changes
60
- - Model information
61
- - Context usage with progress bar
62
- - Session duration
63
- - Cost estimation
64
- - Lines added/removed
65
- - Configuration counts
66
- - Poker hand (entertainment)
209
+ ---
67
210
 
68
- ### Widget Display Styles
211
+ ## Advanced Features
69
212
 
70
- Each widget supports multiple display styles for customization:
213
+ <details>
214
+ <summary><b>Zero Runtime Dependencies</b></summary>
71
215
 
72
- | Style | Description |
73
- |-------|-------------|
74
- | `balanced` | Default balanced style (minimalism + informativeness) |
75
- | `compact` | Maximally compact display |
76
- | `playful` | Fun style with informative emojis |
77
- | `verbose` | Detailed text descriptions |
78
- | `technical` | Technical details (model IDs, milliseconds, etc.) |
79
- | `symbolic` | Symbol-based representation |
80
- | `labeled` | Prefix labels for clarity |
81
- | `indicator` | Bullet indicator prefix |
82
- | `fancy` | Decorative formatting (brackets, quotes) |
83
- | `compact-verbose` | Compact with K-formatted numbers |
216
+ claude-scope is written in pure TypeScript and uses only native Node.js modules. No external runtime dependencies — maximum performance and security.
217
+ </details>
84
218
 
85
- **Note:** This is an early release with basic functionality. Additional features (repository status, session analytics, etc.) are planned for future releases.
219
+ <details>
220
+ <summary><b>Layout & Line System</b></summary>
86
221
 
87
- ## Quick Config
222
+ - **Line 0**: Primary info (model, context, cost, duration, lines, git, dev-server, docker)
223
+ - **Line 1**: Extended (git-tag, config-count)
224
+ - **Line 2**: Activity (cache-metrics, active-tools)
225
+ - **Line 4**: Poker widget (easter egg)
226
+ - **Line 5**: Empty line widget
227
+ </details>
88
228
 
89
- Interactive configuration for widget style and theme:
229
+ <details>
230
+ <summary><b>Widget System</b></summary>
90
231
 
91
- ```bash
92
- claude-scope quick-config
93
- ```
232
+ Each widget implements the `IWidget` interface with lifecycle methods:
233
+ - `initialize()` — Set up the widget
234
+ - `render()` — Generate output
235
+ - `update()` — Handle new data
236
+ - `isEnabled()` — Check if active
94
237
 
95
- This will launch an interactive menu where you can:
96
- 1. Choose display style: balanced, playful, or compact
97
- 2. Choose from 17 available themes
98
- 3. See live preview as you make selections
238
+ Widgets gracefully degrade on errors — if something fails, it returns `null`.
239
+ </details>
99
240
 
100
- Configuration is saved to `~/.claude-scope/config.json`.
241
+ ---
101
242
 
102
- ### Styles
243
+ ## Documentation
103
244
 
104
- - **Balanced**: Clean display with labels (default)
105
- - **Playful**: Fun display with emojis
106
- - **Compact**: Minimal, condensed display
245
+ | Topic | Link |
246
+ |-------|------|
247
+ | Architecture, data flow, providers | [ARCHITECTURE.md](docs/ARCHITECTURE.md) |
248
+ | All widgets, styles, examples | [WIDGETS.md](docs/WIDGETS.md) |
249
+ | Theme system, customization | [THEME-SYSTEM.md](docs/THEME-SYSTEM.md) |
250
+ | Formatters, ANSI colors | [FORMATTERS.md](docs/FORMATTERS.md) |
251
+ | Version history, roadmap | [CHANGELOG.md](docs/CHANGELOG.md) |
107
252
 
108
- ### Themes
253
+ ---
109
254
 
110
- 17 built-in themes available: monokai, nord, dracula, dusty-sage, catppuccin-mocha, cyberpunk-neon, github-dark-dimmed, gray, muted-gray, one-dark-pro, professional-blue, rose-pine, semantic-classic, slate-blue, solarized-dark, tokyo-night, vscode-dark-plus.
255
+ ## Requirements
111
256
 
112
- ## Releasing
257
+ - **Node.js** 18 or higher
258
+ - **Claude Code** CLI
113
259
 
114
- To create a new release:
260
+ ---
115
261
 
116
- 1. Update version in `package.json`
117
- 2. Commit changes
118
- 3. Create and push tag:
262
+ ## License
119
263
 
120
- ```bash
121
- git tag v0.1.0
122
- git push origin main
123
- git push origin v0.1.0
124
- ```
264
+ [MIT](LICENSE.md) — feel free to use this project in your own work!
265
+
266
+ ---
267
+
268
+ <div align="center">
269
+
270
+ **Made with ❤️ by [YuriNachos](https://github.com/YuriNachos)**
125
271
 
126
- The GitHub Actions workflow will:
127
- - Run all tests
128
- - Build the project
129
- - Generate coverage report
130
- - Commit `dist/` to repository
131
- - Create GitHub Release with auto-generated notes
272
+ [GitHub](https://github.com/YuriNachos/claude-scope) · [Issues](https://github.com/YuriNachos/claude-scope/issues) · [Contributing](CONTRIBUTING.md)
132
273
 
133
- **Note:** If tests fail, the release will not be created.
274
+ </div>