Polish README with badges and mermaid diagrams, add release infrastructure

Rewrite README with centered header, shields.io badges, mermaid topology and session key diagrams, restructured installation section with Windows quick start guide, and release documentation. Add CHANGELOG.md for v0.2.0 and Gitea Actions release workflow that builds source archives (tar.gz + zip) and publishes them on tag push. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-26 15:03:31 +01:00
parent 688b6a75f7
commit 59afabd65a
3 changed files with 211 additions and 36 deletions
--- a/README.md
+++ b/README.md
@@ -1,11 +1,24 @@
-# claude-statusline
+<h1 align="center">claude-statusline</h1>

-Monitor your Claude API usage — as a **CLI statusline** on headless servers or a **system tray widget** on desktop machines.
+<p align="center">
+  Monitor your Claude API usage — as a CLI statusline or a system tray widget
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white" alt="Node.js 18+" />
+  <img src="https://img.shields.io/badge/Python-3.9+-3776AB?logo=python&logoColor=white" alt="Python 3.9+" />
+  <img src="https://img.shields.io/badge/Platform-Linux%20|%20macOS%20|%20Windows-informational" alt="Platform: Linux | macOS | Windows" />
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" />
+  <br />
+  <a href="https://git.davoryn.de/calic/claude-statusline/releases"><img src="https://img.shields.io/badge/releases-Gitea-blue?logo=gitea&logoColor=white" alt="Releases" /></a>
+</p>
+
+---
+
+## Overview

 Both components share the same session key and fetcher logic. Install one or both depending on your setup.

-## Components
-
 ### CLI Statusline (Node.js)

 A headless-friendly status bar for Claude Code. Shows context window utilization and token usage as text progress bars, piped into the Claude Code statusline slot.
@@ -24,30 +37,28 @@ Cross-platform system tray icon that shows the 5-hour usage window as a circular

 ## Topology

-```
-                          claude.ai API
-                               |
-                  ┌────────────┴────────────┐
-                  |                         |
-            fetch-usage.js           claude_usage_widget/
-            (cron, Node.js)            fetcher.py thread
-                  |                    (Python, urllib)
-                  |                         |
-                  └────────┬────────────────┘
-                           v
-                  /tmp/claude_usage.json
-                     (shared cache)
-                  ┌────────┴────────────────┐
-                  |                         |
-            statusline.js           claude_usage_widget/
-            (Claude Code)              app.py (pystray)
-                  |                         |
-                  v                         v
-          Claude Code               System tray icon
-            status bar              + right-click menu
+```mermaid
+graph TD
+  API["claude.ai API"]
+  FetchJS["fetch-usage.js<br/>(cron / Node.js)"]
+  FetchPy["fetcher.py thread<br/>(Python / urllib)"]
+  Cache["/tmp/claude_usage.json<br/>(shared cache)"]
+  SL["statusline.js<br/>(Claude Code)"]
+  Widget["app.py<br/>(pystray tray icon)"]
+  CC["Claude Code status bar"]
+  Tray["System tray icon<br/>+ right-click menu"]
+  SK["~/.config/claude-statusline/session-key"]

-  Shared: ~/.config/claude-statusline/session-key
-          /tmp/claude_usage.json
+  API --> FetchJS
+  API --> FetchPy
+  FetchJS --> Cache
+  FetchPy --> Cache
+  Cache --> SL
+  Cache --> Widget
+  SL --> CC
+  Widget --> Tray
+  SK -.->|auth| FetchJS
+  SK -.->|auth| FetchPy
 ```

 Only one fetcher needs to run. Either `fetch-usage.js` (via cron) or the widget's built-in fetcher thread writes to the shared cache at `/tmp/claude_usage.json`. Both consumers read from it:
@@ -59,23 +70,58 @@ If both fetchers happen to run, they write the same format — last writer wins,

 ## Installation

-Run the installer and follow the wizard:
+### Quick Install (from release)
+
+Download the latest archive from the [Releases page](https://git.davoryn.de/calic/claude-statusline/releases) for your platform:
+
+| Platform | Download | Install |
+|----------|----------|---------|
+| **Linux** | `.tar.gz` source archive | Extract, then `bash install.sh` |
+| **macOS** | `.tar.gz` source archive | Extract, then `bash install.sh` |
+| **Windows** | `.zip` source archive | Extract, then run `install.ps1` (see [Windows Quick Start](#windows-quick-start) below) |
+
+> **Planned:** Native installers (`.deb`, `.msi`) are on the roadmap. For now, releases contain source archives.
+
+### Developer Install (from source)
+
+Clone the repository and run the installer wizard:

 **Linux / macOS:**
 ```bash
+git clone https://git.davoryn.de/calic/claude-statusline.git
+cd claude-statusline
 bash install.sh
 ```

 **Windows (PowerShell):**
 ```powershell
+git clone https://git.davoryn.de/calic/claude-statusline.git
+cd claude-statusline
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```

-The wizard will:
-1. Ask which components to install (CLI statusline, desktop widget, or both)
-2. Guide you through session key setup
-3. Configure autostart (widget) or cron (CLI fetcher) as applicable
-4. Set up the Claude Code statusline integration
+### What the wizard does
+
+1. Asks which components to install (CLI statusline, desktop widget, or both)
+2. Guides you through session key setup
+3. Configures autostart (widget) or cron (CLI fetcher) as applicable
+4. Sets up the Claude Code statusline integration
+
+### Windows Quick Start
+
+If you're new to the command line, follow these steps:
+
+1. Go to the [Releases page](https://git.davoryn.de/calic/claude-statusline/releases) and download the latest `.zip` file
+2. Extract the zip to any folder (e.g. `C:\Users\YourName\claude-statusline`)
+3. Open the extracted folder in File Explorer
+4. Right-click `install.ps1` and select **Run with PowerShell**
+   - If you see a security prompt, choose **Run anyway** or **Open**
+   - Alternatively, open PowerShell manually and run:
+     ```powershell
+     powershell -ExecutionPolicy Bypass -File install.ps1
+     ```
+5. The wizard will walk you through component selection and session key setup
+6. To find your session key, see [Session Key](#session-key) below

 ### Prerequisites

@@ -87,11 +133,26 @@ The wizard will:

 ## Session Key

-Both components authenticate via a session cookie from claude.ai:
+Both components authenticate via a session cookie from claude.ai.
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Browser
+  participant Installer
+  participant Config
+
+  User->>Browser: Log into claude.ai
+  User->>Browser: DevTools → Cookies → sessionKey
+  User->>Installer: Paste session key when prompted
+  Installer->>Config: ~/.config/claude-statusline/session-key
+```
+
+**Step by step:**

 1. Log into [claude.ai](https://claude.ai) in any browser
-2. Open DevTools → Application → Cookies → `claude.ai`
-3. Copy the value of the `sessionKey` cookie (starts with `sk-ant-`)
+2. Open DevTools (press `F12`), go to **Application** → **Cookies** → `https://claude.ai`
+3. Copy the value of the `sessionKey` cookie (it starts with `sk-ant-`)
 4. The installer will prompt you to enter it, or set it manually:

 ```bash
@@ -142,6 +203,15 @@ The tray icon arc color indicates usage severity at 10% increments:
 | 80–90% | Deep orange |
 | 90–100% | Red |

+## Releases
+
+Tagged releases are published on [Gitea](https://git.davoryn.de/calic/claude-statusline/releases) following semver (`v0.2.0`, `v0.3.0`, etc.). Each release includes per-OS source archives.
+
+**Planned future additions:**
+- `.deb` package for Debian/Ubuntu
+- `.msi` / `.exe` installer for Windows
+- Homebrew tap for macOS
+
 ## Project Structure

 ```