claude-simple-status 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edin Mujkanovic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+<p align="center">
+  <img src="assets/claude-simple-status-mascot-512.png" width="256" alt="claude-simple-status mascot">
+</p>
+
+# claude-simple-status
+
+[![npm](https://img.shields.io/npm/v/claude-simple-status)](https://www.npmjs.com/package/claude-simple-status)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)]()
+
+A simple, no-frills statusline for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that shows what matters: **git branch, model, context usage, and quota**.
+
+![statusline screenshot](assets/statusline.png)
+
+## Features
+
+- **Zero dependencies** — single Node.js script, no runtime dependencies
+- **Cross-platform** — works on macOS, Linux, and Windows
+- **Non-blocking** — returns cached data instantly, refreshes quota in the background
+- **Color-coded** — green/orange/red percentages at a glance
+- **Git-aware** — shows the current branch name in repos
+- **Timezone-smart** — quota reset time converted to your local timezone
+
+If the quota API is unreachable, a red `ERR` indicator appears at the end and clears automatically once the connection recovers.
+
+## Installation
+
+```bash
+npm install -g claude-simple-status
+```
+
+That's it — Claude Code is configured automatically. The statusline appears immediately.
+
+To uninstall (also cleans up the Claude Code config):
+
+```bash
+npm uninstall -g claude-simple-status
+```
+
+<details>
+<summary>Alternative: shell script (macOS / Linux)</summary>
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/edimuj/claude-simple-status/main/install.sh | bash
+```
+
+</details>
+
+<details>
+<summary>Alternative: PowerShell (Windows)</summary>
+
+```powershell
+irm https://raw.githubusercontent.com/edimuj/claude-simple-status/main/install.ps1 | iex
+```
+
+</details>
+
+<details>
+<summary>Manual installation</summary>
+
+**1. Copy the script**
+
+```bash
+mkdir -p ~/.claude/statusline
+curl -o ~/.claude/statusline/statusline.mjs \
+  https://raw.githubusercontent.com/edimuj/claude-simple-status/main/statusline.mjs
+```
+
+**2. Configure Claude Code**
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node ~/.claude/statusline/statusline.mjs"
+  }
+}
+```
+
+To uninstall, remove `~/.claude/statusline/` and the `"statusLine"` block from settings.json.
+
+</details>
+
+## Requirements
+
+- Claude Code CLI
+- Node.js (v18+)
+
+## How it works
+
+1. Receives model/context info from Claude Code via stdin (JSON)
+2. Reads cached quota data and returns immediately (never blocks the UI)
+3. If the cache is stale (>2 minutes), refreshes from Anthropic's OAuth API in the background
+4. Converts UTC reset time to your local timezone
+5. Outputs a formatted statusline with ANSI colors
+
+Quota data is cached to the system temp directory and refreshed every 2 minutes. Since Claude Code calls the statusline on every message update, this avoids excessive API calls while keeping the data fresh.
+
+## Troubleshooting
+
+If the statusline shows `ERR`, check the error log:
+
+```bash
+# macOS/Linux
+cat /tmp/claude-statusline.log
+
+# Windows (PowerShell)
+Get-Content $env:TEMP\claude-statusline.log
+```
+
+To force a fresh quota fetch, clear the cache:
+
+```bash
+# macOS/Linux
+rm /tmp/claude-statusline-quota.json
+
+# Windows (PowerShell)
+Remove-Item $env:TEMP\claude-statusline-quota.json
+```
+
+## Contributing
+
+Contributions are welcome! This project follows a few principles:
+
+- Single file, zero dependencies
+- Cross-platform (macOS, Linux, Windows)
+- Never block the UI
+
+Open an [issue](https://github.com/edimuj/claude-simple-status/issues) or submit a pull request.
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "claude-simple-status",
+  "version": "1.0.0",
+  "description": "A simple statusline for Claude Code — git branch, model, context usage, and quota at a glance",
+  "type": "module",
+  "bin": {
+    "claude-simple-status": "./statusline.mjs"
+  },
+  "scripts": {
+    "postinstall": "node scripts/setup.mjs install",
+    "preuninstall": "node scripts/setup.mjs uninstall"
+  },
+  "files": [
+    "statusline.mjs",
+    "scripts/setup.mjs"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "statusline",
+    "status-bar",
+    "anthropic",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edimuj/claude-simple-status.git"
+  },
+  "homepage": "https://github.com/edimuj/claude-simple-status",
+  "bugs": {
+    "url": "https://github.com/edimuj/claude-simple-status/issues"
+  },
+  "author": "Edin Mujkanovic",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/setup.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Postinstall / preuninstall hook for claude-simple-status
+// Configures (or removes) the statusLine entry in ~/.claude/settings.json
+
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+
+const SETTINGS_FILE = join(homedir(), '.claude', 'settings.json');
+const COMMAND = 'claude-simple-status';
+
+function readSettings() {
+  try {
+    return JSON.parse(readFileSync(SETTINGS_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeSettings(settings) {
+  mkdirSync(dirname(SETTINGS_FILE), { recursive: true });
+  writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + '\n');
+}
+
+function install() {
+  try {
+    const settings = readSettings() || {};
+
+    if (settings.statusLine) {
+      if (settings.statusLine.command === COMMAND) {
+        console.log('claude-simple-status is already configured.');
+        return;
+      }
+      console.log('');
+      console.log('Note: statusLine is already configured in ~/.claude/settings.json.');
+      console.log('To switch to claude-simple-status, update your settings:');
+      console.log('');
+      console.log('  "statusLine": {');
+      console.log('    "type": "command",');
+      console.log(`    "command": "${COMMAND}"`);
+      console.log('  }');
+      console.log('');
+      return;
+    }
+
+    settings.statusLine = {
+      type: 'command',
+      command: COMMAND
+    };
+
+    writeSettings(settings);
+    console.log('');
+    console.log('claude-simple-status installed!');
+    console.log('Your statusline will appear at the bottom of Claude Code.');
+    console.log('');
+  } catch (err) {
+    console.log(`Note: Could not auto-configure Claude Code (${err.message}).`);
+    console.log('Add this manually to ~/.claude/settings.json:');
+    console.log('');
+    console.log('  "statusLine": {');
+    console.log('    "type": "command",');
+    console.log(`    "command": "${COMMAND}"`);
+    console.log('  }');
+    console.log('');
+  }
+}
+
+function uninstall() {
+  try {
+    const settings = readSettings();
+    if (!settings || !settings.statusLine) return;
+    if (settings.statusLine.command !== COMMAND) return;
+
+    delete settings.statusLine;
+    writeSettings(settings);
+    console.log('');
+    console.log('claude-simple-status removed from Claude Code settings.');
+    console.log('');
+  } catch {
+    // Best-effort cleanup, don't fail the uninstall
+  }
+}
+
+const action = process.argv[2];
+if (action === 'install') install();
+else if (action === 'uninstall') uninstall();

package/statusline.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+// Claude Code Statusline - Shows Branch | Model | Context % | Next Reset | 5h Quota % | 7d Quota %
+// Cross-platform Node.js version (no dependencies)
+
+import { readFileSync, writeFileSync, mkdirSync, rmdirSync, statSync, existsSync, appendFileSync } from 'fs';
+import { homedir, tmpdir } from 'os';
+import { join } from 'path';
+import { spawn, execSync } from 'child_process';
+import { request } from 'https';
+
+// ANSI color codes
+const GREEN = '\x1b[0;32m';
+const ORANGE = '\x1b[0;33m';
+const RED = '\x1b[0;31m';
+const CYAN = '\x1b[0;36m';
+const YELLOW_BOLD = '\x1b[1;33m';
+const RESET = '\x1b[0m';
+
+// File paths
+const CREDS_FILE = join(homedir(), '.claude', '.credentials.json');
+const CACHE_FILE = join(tmpdir(), 'claude-statusline-quota.json');
+const LOCK_DIR = join(tmpdir(), 'claude-statusline-quota.lock');
+const ERROR_FILE = join(tmpdir(), 'claude-statusline-error');
+const LOG_FILE = join(tmpdir(), 'claude-statusline.log');
+const CACHE_MAX_AGE = 120; // seconds
+
+// Color a percentage value based on thresholds
+function colorPct(val) {
+    if (typeof val !== 'number' || isNaN(val)) {
+        return val === 'N/A' ? 'N/A' : `${val}`;
+    }
+    const intVal = Math.floor(val);
+    if (intVal <= 50) return `${GREEN}${val}%${RESET}`;
+    if (intVal <= 69) return `${ORANGE}${val}%${RESET}`;
+    return `${RED}${val}%${RESET}`;
+}
+
+// Get file age in seconds
+function getFileAge(filepath) {
+    try {
+        const stats = statSync(filepath);
+        return Math.floor((Date.now() - stats.mtimeMs) / 1000);
+    } catch {
+        return Infinity;
+    }
+}
+
+// Read JSON file safely
+function readJsonFile(filepath) {
+    try {
+        return JSON.parse(readFileSync(filepath, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+// Clean up stale lock (older than 30s)
+function cleanStaleLock() {
+    if (existsSync(LOCK_DIR) && getFileAge(LOCK_DIR) > 30) {
+        try { rmdirSync(LOCK_DIR); } catch {}
+    }
+}
+
+// Acquire lock atomically (mkdir fails if exists)
+function acquireLock() {
+    try {
+        mkdirSync(LOCK_DIR);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+// Release lock
+function releaseLock() {
+    try { rmdirSync(LOCK_DIR); } catch {}
+}
+
+// Log error with timestamp
+function logError(msg) {
+    const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    try {
+        appendFileSync(LOG_FILE, `[${ts}] ${msg}\n`);
+        writeFileSync(ERROR_FILE, msg);
+        // Trim log to last 50 lines
+        const lines = readFileSync(LOG_FILE, 'utf8').split('\n').filter(Boolean);
+        if (lines.length > 50) {
+            writeFileSync(LOG_FILE, lines.slice(-50).join('\n') + '\n');
+        }
+    } catch {}
+}
+
+// Clear error state
+function clearError() {
+    try { writeFileSync(ERROR_FILE, ''); } catch {}
+}
+
+// Spawn background refresh process
+function refreshInBackground(token) {
+    const child = spawn(process.execPath, [
+        '-e',
+        `
+        const { mkdirSync, rmdirSync, writeFileSync, readFileSync, appendFileSync } = require('fs');
+        const { request } = require('https');
+        const CACHE_FILE = ${JSON.stringify(CACHE_FILE)};
+        const LOCK_DIR = ${JSON.stringify(LOCK_DIR)};
+        const ERROR_FILE = ${JSON.stringify(ERROR_FILE)};
+        const LOG_FILE = ${JSON.stringify(LOG_FILE)};
+
+        function logError(msg) {
+            const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+            try {
+                appendFileSync(LOG_FILE, '[' + ts + '] ' + msg + '\\n');
+                writeFileSync(ERROR_FILE, msg);
+                const lines = readFileSync(LOG_FILE, 'utf8').split('\\n').filter(Boolean);
+                if (lines.length > 50) writeFileSync(LOG_FILE, lines.slice(-50).join('\\n') + '\\n');
+            } catch {}
+        }
+
+        const req = request({
+            hostname: 'api.anthropic.com',
+            path: '/api/oauth/usage',
+            method: 'GET',
+            headers: {
+                'Authorization': 'Bearer ${token}',
+                'anthropic-beta': 'oauth-2025-04-20',
+                'Accept': 'application/json',
+                'User-Agent': 'claude-code/2.1.12'
+            },
+            timeout: 10000
+        }, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                if (res.statusCode === 200) {
+                    try {
+                        JSON.parse(data);
+                        writeFileSync(CACHE_FILE, data);
+                        try { writeFileSync(ERROR_FILE, ''); } catch {}
+                    } catch { logError('Invalid JSON'); }
+                } else if (res.statusCode !== 401) {
+                    // Skip 401 - token not ready yet at startup, will retry next cycle
+                    logError('HTTP ' + res.statusCode);
+                }
+                try { rmdirSync(LOCK_DIR); } catch {}
+            });
+        });
+        req.on('error', () => { logError('Connection failed'); try { rmdirSync(LOCK_DIR); } catch {} });
+        req.on('timeout', () => { req.destroy(); logError('Timeout'); try { rmdirSync(LOCK_DIR); } catch {} });
+        req.end();
+        `
+    ], {
+        detached: true,
+        stdio: 'ignore'
+    });
+    child.unref();
+}
+
+// Convert UTC ISO time to local HH:mm
+function toLocalTime(isoString) {
+    if (!isoString) return '--:--';
+    try {
+        const date = new Date(isoString);
+        // Round to nearest minute
+        date.setSeconds(date.getSeconds() + 30);
+        return date.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' });
+    } catch {
+        return '--:--';
+    }
+}
+
+// Get current git branch name
+function getGitBranch() {
+    try {
+        return execSync('git rev-parse --abbrev-ref HEAD', {
+            timeout: 1000,
+            stdio: ['ignore', 'pipe', 'ignore']
+        }).toString().trim();
+    } catch {
+        return null;
+    }
+}
+
+// Main
+async function main() {
+    // Read stdin
+    let input = '';
+    for await (const chunk of process.stdin) {
+        input += chunk;
+    }
+
+    // Parse Claude Code input
+    let model = 'Unknown';
+    let contextUsed = 0;
+    try {
+        const data = JSON.parse(input);
+        model = data.model?.display_name || 'Unknown';
+        contextUsed = data.context_window?.used_percentage || 0;
+    } catch {}
+
+    // Get OAuth token
+    let token = null;
+    const creds = readJsonFile(CREDS_FILE);
+    if (creds?.claudeAiOauth?.accessToken) {
+        token = creds.claudeAiOauth.accessToken;
+    }
+
+    // Read cached quota data (never block on fetch)
+    let quotaData = readJsonFile(CACHE_FILE);
+
+    // Check if refresh needed and spawn background fetch
+    if (token) {
+        cleanStaleLock();
+        const cacheAge = getFileAge(CACHE_FILE);
+        const needRefresh = !quotaData || cacheAge >= CACHE_MAX_AGE;
+
+        if (needRefresh && acquireLock()) {
+            refreshInBackground(token);
+        }
+    }
+
+    // Parse quota data
+    let fiveHourPct = '?';
+    let sevenDayPct = '?';
+    let resetLocal = '--:--';
+
+    if (quotaData) {
+        if (quotaData.five_hour === null || quotaData.seven_day === null) {
+            // Organization/team plan without individual quota
+            fiveHourPct = 'N/A';
+            sevenDayPct = 'N/A';
+            resetLocal = 'N/A';
+        } else {
+            fiveHourPct = quotaData.five_hour?.utilization ?? '?';
+            sevenDayPct = quotaData.seven_day?.utilization ?? '?';
+            resetLocal = toLocalTime(quotaData.five_hour?.resets_at);
+        }
+    }
+
+    // Check for error state
+    let hasError = false;
+    try {
+        const errContent = readFileSync(ERROR_FILE, 'utf8').trim();
+        hasError = errContent.length > 0;
+    } catch {}
+
+    // Get git branch
+    const branch = getGitBranch();
+
+    // Build output
+    let output = `${branch ? `${YELLOW_BOLD}${branch}${RESET} | ` : ''}${CYAN}${model}${RESET} | ${colorPct(contextUsed)} | ${resetLocal} | 5h:${colorPct(fiveHourPct)} | 7d:${colorPct(sevenDayPct)}`;
+    if (hasError) {
+        output += ` | ${RED}ERR${RESET}`;
+    }
+
+    process.stdout.write(output);
+}
+
+main().catch(() => process.exit(1));