feat: Add npx CLI package for Copilot token usage analysis

.github/agents/refactor.agent.md

@@ -1,7 +1,7 @@
 ---
 description: "Improve code quality, apply security best practices, and enhance design whilst maintaining green tests."
 name: "Code Refactor - Improve Quality & Security"
-tools: ["execute/runTests", "execute/getTerminalOutput", "execute/runInTerminal", "read/terminalLastCommand", "read/terminalSelection", "search/codebase", "read/problems", "execute/testFailure"]
+tools: ["execute/getTerminalOutput", "execute/runInTerminal", "read/terminalLastCommand", "read/terminalSelection", "search/codebase", "read/problems", "execute/testFailure"]
 ---
 
 # Code Refactor - Improve Quality & Security

.github/workflows/cli-build.yml

@@ -0,0 +1,96 @@
+name: CLI - Build & Validate
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'cli/**'
+      - 'src/sessionDiscovery.ts'
+      - 'src/sessionParser.ts'
+      - 'src/tokenEstimation.ts'
+      - 'src/maturityScoring.ts'
+      - 'src/usageAnalysis.ts'
+      - 'src/opencode.ts'
+      - 'src/types.ts'
+      - 'src/tokenEstimators.json'
+      - 'src/modelPricing.json'
+      - 'src/toolNames.json'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'cli/**'
+      - 'src/sessionDiscovery.ts'
+      - 'src/sessionParser.ts'
+      - 'src/tokenEstimation.ts'
+      - 'src/maturityScoring.ts'
+      - 'src/usageAnalysis.ts'
+      - 'src/opencode.ts'
+      - 'src/types.ts'
+      - 'src/tokenEstimators.json'
+      - 'src/modelPricing.json'
+      - 'src/toolNames.json'
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-validate:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install extension dependencies
+        run: npm ci
+
+      - name: Install CLI dependencies
+        working-directory: cli
+        run: npm ci
+
+      - name: Build CLI
+        working-directory: cli
+        run: npm run build
+
+      - name: Validate CLI --help
+        working-directory: cli
+        run: node dist/cli.js --help
+
+      - name: Validate CLI --version
+        working-directory: cli
+        run: node dist/cli.js --version
+
+      - name: Validate stats command
+        working-directory: cli
+        run: node dist/cli.js stats --verbose
+
+      - name: Validate usage command
+        working-directory: cli
+        run: node dist/cli.js usage
+
+      - name: Validate environmental command
+        working-directory: cli
+        run: node dist/cli.js environmental
+
+      - name: Validate fluency command
+        working-directory: cli
+        run: node dist/cli.js fluency --tips
+
+      - name: Build production bundle
+        working-directory: cli
+        run: npm run build:production
+
+      - name: Verify production bundle runs
+        working-directory: cli
+        run: node dist/cli.js --help

.github/workflows/cli-publish.yml

@@ -0,0 +1,98 @@
+name: CLI - Publish to npm
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_bump:
+        description: 'Version bump type'
+        required: true
+        default: 'patch'
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      dry_run:
+        description: 'Dry run (do not actually publish)'
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: cli
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: Install extension dependencies
+        run: npm ci
+        working-directory: .
+
+      - name: Install CLI dependencies
+        run: npm ci
+
+      - name: Build production bundle
+        run: npm run build:production
+
+      - name: Validate CLI works
+        run: node dist/cli.js --help
+
+      - name: Bump version
+        run: npm version ${{ inputs.version_bump }} --no-git-tag-version
+
+      - name: Get new version
+        id: version
+        run: echo "version=$(node -p 'require("./package.json").version')" >> "$GITHUB_OUTPUT"
+
+      - name: Publish to npm
+        if: ${{ !inputs.dry_run }}
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Dry run publish
+        if: ${{ inputs.dry_run }}
+        run: npm publish --access public --dry-run
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Commit version bump
+        if: ${{ !inputs.dry_run }}
+        run: |
+          cd ..
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add cli/package.json cli/package-lock.json
+          git commit -m "chore(cli): bump version to v${{ steps.version.outputs.version }}"
+          git push
+
+      - name: Summary
+        run: |
+          echo "## CLI Package Published 📦" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **Version:** v${{ steps.version.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **Bump:** ${{ inputs.version_bump }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **Dry run:** ${{ inputs.dry_run }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          if [ "${{ inputs.dry_run }}" = "false" ]; then
+            echo "Install with: \`npx copilot-token-tracker-cli\`" >> "$GITHUB_STEP_SUMMARY"
+          fi

README.md

@@ -1,10 +1,22 @@
 # GitHub Copilot Token Tracker
 
-A VS Code extension that shows your daily and monthly GitHub Copilot estimated token usage in the status bar. It reads GitHub Copilot Chat session logs and computes local aggregates.
+A VS Code extension that shows your daily and monthly GitHub Copilot estimated token usage and AI Fluency. It reads the local session logs and computes local aggregates.
 
-Optionally, you can enable an **opt-in Azure Storage backend** to sync aggregates from all your VS Code instances (across machines, profiles, and windows) into **your own Azure Storage account** for cross-device reporting.
+## Supported AI engineering tools:
 
-You can also use a **shared Azure Storage account** (a “shared storage server” for the team) so that multiple developers sync into the same dataset and a team lead can view aggregated usage across the team (with explicit per-user consent).
+- VS Code + GitHub Copilot
+- VS Code Insiders + GitHub Copilot
+- GitHub Copilot CLI
+- OpenCode + GitHub Copilot (not tested with other AI tooling)
+
+### CLI
+
+We also added a CLI that you can run as an npx package:
+```bash
+npx copilot-token-tracker usage
+```
+
+For screenshots and examples of the CLI output, see the [CLI README](cli/README.md).
 
 ## Features
 

cli/.npmignore

@@ -0,0 +1,6 @@
+src/
+tsconfig.json
+esbuild.js
+node_modules/
+*.ts
+*.map

cli/README.md

@@ -0,0 +1,99 @@
+# Copilot Token Tracker CLI
+
+Command-line interface for analyzing GitHub Copilot token usage from local session files. Works anywhere Copilot Chat stores its session data.
+
+## Quick Start
+
+```bash
+# Run directly with npx (no install required)
+npx copilot-token-tracker-cli stats
+
+# Or install globally
+npm install -g copilot-token-tracker-cli
+copilot-token-tracker stats
+```
+
+## Commands
+
+### `stats` - Session Overview
+
+Show discovered session files, sessions, chat turns, and token counts.
+
+```bash
+copilot-token-tracker stats
+copilot-token-tracker stats --verbose  # Show per-folder breakdown
+```
+
+![Terminal Statistics](../docs/images/Terminal%20Statistics.png)
+
+### `usage` - Token Usage Report
+
+Show token usage broken down by time period.
+
+```bash
+copilot-token-tracker usage
+copilot-token-tracker usage --models  # Show per-model breakdown
+copilot-token-tracker usage --cost    # Show estimated cost
+```
+
+![Terminal Usage](../docs/images/Terminal%20Usage.png)
+
+### `environmental` - Environmental Impact
+
+Show environmental impact of your Copilot usage (CO₂ emissions, water usage, tree equivalents).
+
+```bash
+copilot-token-tracker environmental
+copilot-token-tracker env  # Short alias
+```
+
+### `fluency` - Fluency Score
+
+Show your Copilot Fluency Score across multiple categories (Prompt Engineering, Context Engineering, Agentic, Tool Usage, Customization, Team Collaboration).
+
+```bash
+copilot-token-tracker fluency
+copilot-token-tracker fluency --tips  # Show improvement tips, if there are any
+```
+
+### `diagnostics` - Search Locations & Stats
+
+Show all locations searched for session files, whether each path exists, and per-location stats (files, sessions, chat turns, tokens).
+
+```bash
+copilot-token-tracker diagnostics
+```
+
+![Terminal Diagnostics](../docs/images/Terminal%20Diagnostitcs.png)
+
+## Data Sources
+
+The CLI scans the same session files that the [Copilot Token Tracker VS Code extension](https://marketplace.visualstudio.com/items?itemName=RobBos.copilot-token-tracker) uses:
+
+- **VS Code** (Stable, Insiders, Exploration) workspace and global storage
+- **VSCodium** and **Cursor** editor sessions
+- **VS Code Remote** / Codespaces sessions
+- **Copilot CLI** agent mode sessions
+- **OpenCode** sessions (JSON and SQLite)
+
+## Development
+
+```bash
+# From the repository root
+npm run cli:build        # Build the CLI
+npm run cli:stats        # Run stats command
+npm run cli:usage        # Run usage command
+npm run cli:environmental # Run environmental command
+npm run cli:fluency      # Run fluency command
+npm run cli:diagnostics  # Run diagnostics command
+npm run cli -- --help    # Run any CLI command
+```
+
+## Requirements
+
+- Node.js 18 or later
+- GitHub Copilot Chat session files on the local machine
+
+## License
+
+MIT - See [LICENSE](../LICENSE) for details.