copilot-usage-tui 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Bisov
+
+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,83 @@
+# copilot-usage-tui
+
+A terminal UI for viewing your GitHub Copilot premium request usage.
+
+![Tokyo Night themed](https://img.shields.io/badge/theme-Tokyo%20Night-7aa2f7)
+
+## Features
+
+- View your monthly premium request usage with a visual progress bar
+- Model breakdown chart showing usage across different AI models
+- Cost summary (gross, discount, net)
+- End-of-month usage prediction with overage cost estimation
+- Interactive plan/quota setup on first run
+- Manual refresh with `r` key
+
+## Requirements
+
+- [Bun](https://bun.sh/) runtime
+- [GitHub CLI](https://cli.github.com/) (`gh`) authenticated with the `user` scope
+
+## Installation
+
+### Quick run (no install)
+
+```bash
+bunx copilot-usage-tui
+```
+
+### Install globally
+
+```bash
+bun install -g copilot-usage-tui
+```
+
+Then run:
+
+```bash
+copilot-usage-tui
+```
+
+### From source
+
+```bash
+git clone https://github.com/abisov/copilot-usage-tui.git
+cd copilot-usage-tui
+bun install
+bun run start
+```
+
+## Setup
+
+Ensure your GitHub CLI has the required `user` scope:
+
+```bash
+gh auth refresh -h github.com -s user
+```
+
+## Usage
+
+On first run, you'll be prompted to select your Copilot plan to set your monthly quota.
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `r` | Refresh usage data |
+| `s` | Open settings (change plan) |
+| `q` | Quit |
+
+## Configuration
+
+Config is stored at `~/.copilot-usage.json` and contains your selected plan and quota.
+
+## How it works
+
+Uses an undocumented GitHub billing API endpoint accessed via the `gh` CLI:
+```
+gh api users/{username}/settings/billing/premium_request/usage
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "copilot-usage-tui",
+  "version": "1.0.0",
+  "description": "Terminal UI for viewing GitHub Copilot premium request usage",
+  "type": "module",
+  "bin": {
+    "copilot-usage-tui": "./src/index.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abisov/copilot-usage-tui.git"
+  },
+  "keywords": ["github", "copilot", "tui", "terminal", "cli", "usage"],
+  "author": "abisov",
+  "license": "MIT",
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch run src/index.ts"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.1.74"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  }
+}

package/src/api/auth.ts

@@ -0,0 +1,148 @@
+import type { AuthStatus } from "../types.ts"
+
+/**
+ * Check if gh CLI is installed
+ */
+async function isGhInstalled(): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(["which", "gh"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+    const exitCode = await proc.exited
+    return exitCode === 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Run gh auth status and parse the output
+ */
+async function getGhAuthStatus(): Promise<{
+  authenticated: boolean
+  hasUserScope: boolean
+  username?: string
+}> {
+  try {
+    const proc = Bun.spawn(["gh", "auth", "status"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+    
+    // gh auth status outputs to stderr
+    const stderr = await new Response(proc.stderr).text()
+    const stdout = await new Response(proc.stdout).text()
+    const output = stderr + stdout
+    const exitCode = await proc.exited
+    
+    if (exitCode !== 0) {
+      return { authenticated: false, hasUserScope: false }
+    }
+    
+    // Parse username from "Logged in to github.com account USERNAME"
+    const usernameMatch = output.match(/Logged in to github\.com account (\w+)/)
+    const username = usernameMatch?.[1]
+    
+    // Check for 'user' scope in token scopes
+    // Format: Token scopes: 'gist', 'read:org', 'repo', 'user', 'workflow'
+    const scopesLine = output.match(/Token scopes:\s*(.+)/)
+    const scopesStr = scopesLine?.[1] || ""
+    // Extract all quoted scope names
+    const scopeMatches = scopesStr.match(/'([^']+)'/g) || []
+    const scopes = scopeMatches.map(s => s.replace(/'/g, ""))
+    const hasUserScope = scopes.includes("user")
+    
+    return {
+      authenticated: true,
+      hasUserScope,
+      username,
+    }
+  } catch {
+    return { authenticated: false, hasUserScope: false }
+  }
+}
+
+/**
+ * Check full authentication status
+ */
+export async function checkAuth(): Promise<AuthStatus> {
+  const ghInstalled = await isGhInstalled()
+  
+  if (!ghInstalled) {
+    return {
+      ghInstalled: false,
+      authenticated: false,
+      hasUserScope: false,
+      error: "GitHub CLI (gh) is not installed",
+    }
+  }
+  
+  const { authenticated, hasUserScope, username } = await getGhAuthStatus()
+  
+  if (!authenticated) {
+    return {
+      ghInstalled: true,
+      authenticated: false,
+      hasUserScope: false,
+      error: "Not authenticated with GitHub CLI",
+    }
+  }
+  
+  if (!hasUserScope) {
+    return {
+      ghInstalled: true,
+      authenticated: true,
+      hasUserScope: false,
+      username,
+      error: "Missing 'user' scope - run: gh auth refresh -s user",
+    }
+  }
+  
+  return {
+    ghInstalled: true,
+    authenticated: true,
+    hasUserScope: true,
+    username,
+  }
+}
+
+/**
+ * Get auth instructions for the user
+ */
+export function getAuthInstructions(status: AuthStatus): string[] {
+  if (!status.ghInstalled) {
+    return [
+      "GitHub CLI is not installed.",
+      "",
+      "Install it from: https://cli.github.com/",
+      "",
+      "Or use Homebrew:",
+      "  brew install gh",
+    ]
+  }
+  
+  if (!status.authenticated) {
+    return [
+      "GitHub CLI is not authenticated.",
+      "",
+      "Run this command in your terminal:",
+      "  gh auth login",
+      "",
+      "Then press [r] to retry.",
+    ]
+  }
+  
+  if (!status.hasUserScope) {
+    return [
+      "GitHub CLI is missing the required 'user' scope.",
+      "",
+      "Run this command in your terminal:",
+      "  gh auth refresh -h github.com -s user",
+      "",
+      "Then press [r] to retry.",
+    ]
+  }
+  
+  return ["Authentication successful!"]
+}

package/src/api/github.ts

@@ -0,0 +1,92 @@
+import type { UsageResponse, UsageSummary } from "../types.ts"
+
+/**
+ * Get the current authenticated username
+ */
+export async function getUsername(): Promise<string | null> {
+  try {
+    const proc = Bun.spawn(["gh", "api", "user", "--jq", ".login"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+    
+    const stdout = await new Response(proc.stdout).text()
+    const exitCode = await proc.exited
+    
+    if (exitCode !== 0) {
+      return null
+    }
+    
+    return stdout.trim()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Fetch usage data from GitHub API
+ */
+export async function fetchUsage(username: string): Promise<UsageResponse | null> {
+  try {
+    const proc = Bun.spawn(
+      ["gh", "api", `users/${username}/settings/billing/premium_request/usage`],
+      {
+        stdout: "pipe",
+        stderr: "pipe",
+      }
+    )
+    
+    const stdout = await new Response(proc.stdout).text()
+    const exitCode = await proc.exited
+    
+    if (exitCode !== 0) {
+      return null
+    }
+    
+    return JSON.parse(stdout) as UsageResponse
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Parse usage response into a summary
+ */
+export function parseUsageSummary(response: UsageResponse): UsageSummary {
+  let totalRequests = 0
+  let grossAmount = 0
+  let discountAmount = 0
+  let netAmount = 0
+  
+  for (const item of response.usageItems) {
+    totalRequests += item.grossQuantity
+    grossAmount += item.grossAmount
+    discountAmount += item.discountAmount
+    netAmount += item.netAmount
+  }
+  
+  // Sort items by grossQuantity descending
+  const sortedItems = [...response.usageItems].sort(
+    (a, b) => b.grossQuantity - a.grossQuantity
+  )
+  
+  return {
+    user: response.user,
+    year: response.timePeriod.year,
+    month: response.timePeriod.month,
+    totalRequests: Math.round(totalRequests),
+    grossAmount,
+    discountAmount,
+    netAmount,
+    items: sortedItems,
+  }
+}
+
+/**
+ * Fetch and parse usage data
+ */
+export async function getUsageSummary(username: string): Promise<UsageSummary | null> {
+  const response = await fetchUsage(username)
+  if (!response) return null
+  return parseUsageSummary(response)
+}

package/src/config/config.ts

@@ -0,0 +1,70 @@
+import { homedir } from "os"
+import { join } from "path"
+import type { Config } from "../types.ts"
+
+const CONFIG_FILE = join(homedir(), ".copilot-usage.json")
+
+/**
+ * Check if config file exists
+ */
+export async function hasConfig(): Promise<boolean> {
+  try {
+    const file = Bun.file(CONFIG_FILE)
+    return await file.exists()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Load config from file
+ */
+export async function loadConfig(): Promise<Config | null> {
+  try {
+    const file = Bun.file(CONFIG_FILE)
+    if (!(await file.exists())) {
+      return null
+    }
+    const text = await file.text()
+    const config = JSON.parse(text) as Config
+    
+    // Validate config
+    if (typeof config.quota !== "number" || config.quota <= 0) {
+      return null
+    }
+    if (typeof config.plan !== "string") {
+      return null
+    }
+    
+    return config
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Save config to file
+ */
+export async function saveConfig(config: Config): Promise<void> {
+  const text = JSON.stringify(config, null, 2)
+  await Bun.write(CONFIG_FILE, text)
+}
+
+/**
+ * Delete config file
+ */
+export async function deleteConfig(): Promise<void> {
+  try {
+    const { unlink } = await import("fs/promises")
+    await unlink(CONFIG_FILE)
+  } catch {
+    // File might not exist, that's fine
+  }
+}
+
+/**
+ * Get config file path (for display purposes)
+ */
+export function getConfigPath(): string {
+  return CONFIG_FILE
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+import { App } from "./ui/app.ts"
+
+async function main() {
+  try {
+    await App.create()
+  } catch (error) {
+    console.error("Failed to start application:", error)
+    process.exit(1)
+  }
+}
+
+main()

package/src/types.ts

@@ -0,0 +1,90 @@
+// GitHub API Response Types
+
+export interface UsageItem {
+  product: string
+  sku: string
+  model: string
+  unitType: string
+  pricePerUnit: number
+  grossQuantity: number
+  grossAmount: number
+  discountQuantity: number
+  discountAmount: number
+  netQuantity: number
+  netAmount: number
+}
+
+export interface UsageResponse {
+  timePeriod: {
+    year: number
+    month: number
+  }
+  user: string
+  usageItems: UsageItem[]
+}
+
+// Aggregated usage data for display
+export interface UsageSummary {
+  user: string
+  year: number
+  month: number
+  totalRequests: number
+  grossAmount: number
+  discountAmount: number
+  netAmount: number
+  items: UsageItem[]
+}
+
+// Config stored in ~/.copilot-usage.json
+export interface Config {
+  quota: number
+  plan: string
+}
+
+// Copilot plan options
+export interface PlanOption {
+  name: string
+  label: string
+  quota: number
+  description: string
+}
+
+export const PLAN_OPTIONS: PlanOption[] = [
+  { name: "free", label: "Free", quota: 50, description: "50 requests/month" },
+  { name: "pro", label: "Pro", quota: 300, description: "300 requests/month" },
+  { name: "pro_plus", label: "Pro+", quota: 1500, description: "1,500 requests/month" },
+  { name: "business", label: "Business", quota: 300, description: "300 requests/month" },
+  { name: "enterprise", label: "Enterprise", quota: 1000, description: "1,000 requests/month" },
+  { name: "custom", label: "Custom", quota: 0, description: "Enter custom value" },
+]
+
+// Application view states
+export type ViewState = "loading" | "setup" | "auth" | "dashboard" | "settings"
+
+// Auth status
+export interface AuthStatus {
+  ghInstalled: boolean
+  authenticated: boolean
+  hasUserScope: boolean
+  username?: string
+  error?: string
+}
+
+// Color theme (Tokyo Night)
+export const THEME = {
+  bg: "#1a1b26",
+  bgDark: "#16161e",
+  bgHighlight: "#292e42",
+  border: "#3b4261",
+  borderHighlight: "#545c7e",
+  fg: "#c0caf5",
+  fgDark: "#a9b1d6",
+  fgMuted: "#565f89",
+  blue: "#7aa2f7",
+  cyan: "#7dcfff",
+  green: "#9ece6a",
+  yellow: "#e0af68",
+  red: "#f7768e",
+  magenta: "#bb9af7",
+  orange: "#ff9e64",
+} as const