Skip to content

Commit 9ece11d

Browse files
Copilotrajbos
Copilot
and
rajbos
authored
feat: Add npx CLI package for Copilot token usage analysis (#433)
* feat: add CLI package with stats, usage, environmental, and fluency commands * feat: add CLI workflows, README, and npmignore * fix: address code review - OpenCode virtual paths, extracted constants, test validation * remove unknown toolconfig * Fix cli test script * fix: simplify tips display logic in fluency command * Docs updated * update package ownership --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: rajbos <6085745+rajbos@users.noreply.github.com> Co-authored-by: Rob Bos <rajbos@users.noreply.github.com>
1 parent 501d4cf commit 9ece11d

23 files changed

+2335
-6
lines changed

‎.github/agents/refactor.agent.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: "Improve code quality, apply security best practices, and enhance design whilst maintaining green tests."
33
name: "Code Refactor - Improve Quality & Security"
4-
tools: ["execute/runTests", "execute/getTerminalOutput", "execute/runInTerminal", "read/terminalLastCommand", "read/terminalSelection", "search/codebase", "read/problems", "execute/testFailure"]
4+
tools: ["execute/getTerminalOutput", "execute/runInTerminal", "read/terminalLastCommand", "read/terminalSelection", "search/codebase", "read/problems", "execute/testFailure"]
55
---
66

77
# Code Refactor - Improve Quality & Security

‎.github/workflows/cli-build.yml‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
name: CLI - Build & Validate
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'cli/**'
8+
- 'src/sessionDiscovery.ts'
9+
- 'src/sessionParser.ts'
10+
- 'src/tokenEstimation.ts'
11+
- 'src/maturityScoring.ts'
12+
- 'src/usageAnalysis.ts'
13+
- 'src/opencode.ts'
14+
- 'src/types.ts'
15+
- 'src/tokenEstimators.json'
16+
- 'src/modelPricing.json'
17+
- 'src/toolNames.json'
18+
pull_request:
19+
branches: [main]
20+
paths:
21+
- 'cli/**'
22+
- 'src/sessionDiscovery.ts'
23+
- 'src/sessionParser.ts'
24+
- 'src/tokenEstimation.ts'
25+
- 'src/maturityScoring.ts'
26+
- 'src/usageAnalysis.ts'
27+
- 'src/opencode.ts'
28+
- 'src/types.ts'
29+
- 'src/tokenEstimators.json'
30+
- 'src/modelPricing.json'
31+
- 'src/toolNames.json'
32+
33+
permissions:
34+
contents: read
35+
36+
jobs:
37+
build-and-validate:
38+
runs-on: ubuntu-latest
39+
strategy:
40+
matrix:
41+
node-version: [18, 20, 22]
42+
steps:
43+
- name: Harden Runner
44+
uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
45+
with:
46+
egress-policy: audit
47+
48+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
49+
50+
- name: Setup Node.js ${{ matrix.node-version }}
51+
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
52+
with:
53+
node-version: ${{ matrix.node-version }}
54+
55+
- name: Install extension dependencies
56+
run: npm ci
57+
58+
- name: Install CLI dependencies
59+
working-directory: cli
60+
run: npm ci
61+
62+
- name: Build CLI
63+
working-directory: cli
64+
run: npm run build
65+
66+
- name: Validate CLI --help
67+
working-directory: cli
68+
run: node dist/cli.js --help
69+
70+
- name: Validate CLI --version
71+
working-directory: cli
72+
run: node dist/cli.js --version
73+
74+
- name: Validate stats command
75+
working-directory: cli
76+
run: node dist/cli.js stats --verbose
77+
78+
- name: Validate usage command
79+
working-directory: cli
80+
run: node dist/cli.js usage
81+
82+
- name: Validate environmental command
83+
working-directory: cli
84+
run: node dist/cli.js environmental
85+
86+
- name: Validate fluency command
87+
working-directory: cli
88+
run: node dist/cli.js fluency --tips
89+
90+
- name: Build production bundle
91+
working-directory: cli
92+
run: npm run build:production
93+
94+
- name: Verify production bundle runs
95+
working-directory: cli
96+
run: node dist/cli.js --help

‎.github/workflows/cli-publish.yml‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
name: CLI - Publish to npm
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
version_bump:
7+
description: 'Version bump type'
8+
required: true
9+
default: 'patch'
10+
type: choice
11+
options:
12+
- patch
13+
- minor
14+
- major
15+
dry_run:
16+
description: 'Dry run (do not actually publish)'
17+
required: false
18+
default: false
19+
type: boolean
20+
21+
permissions:
22+
contents: write
23+
24+
jobs:
25+
publish:
26+
runs-on: ubuntu-latest
27+
defaults:
28+
run:
29+
working-directory: cli
30+
steps:
31+
- name: Harden Runner
32+
uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
33+
with:
34+
egress-policy: audit
35+
36+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
37+
with:
38+
token: ${{ secrets.GITHUB_TOKEN }}
39+
40+
- name: Setup Node.js
41+
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
42+
with:
43+
node-version: 20
44+
registry-url: https://registry.npmjs.org
45+
46+
- name: Install extension dependencies
47+
run: npm ci
48+
working-directory: .
49+
50+
- name: Install CLI dependencies
51+
run: npm ci
52+
53+
- name: Build production bundle
54+
run: npm run build:production
55+
56+
- name: Validate CLI works
57+
run: node dist/cli.js --help
58+
59+
- name: Bump version
60+
run: npm version ${{ inputs.version_bump }} --no-git-tag-version
61+
62+
- name: Get new version
63+
id: version
64+
run: echo "version=$(node -p 'require("./package.json").version')" >> "$GITHUB_OUTPUT"
65+
66+
- name: Publish to npm
67+
if: ${{ !inputs.dry_run }}
68+
run: npm publish --access public
69+
env:
70+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
71+
72+
- name: Dry run publish
73+
if: ${{ inputs.dry_run }}
74+
run: npm publish --access public --dry-run
75+
env:
76+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
77+
78+
- name: Commit version bump
79+
if: ${{ !inputs.dry_run }}
80+
run: |
81+
cd ..
82+
git config user.name "github-actions[bot]"
83+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
84+
git add cli/package.json cli/package-lock.json
85+
git commit -m "chore(cli): bump version to v${{ steps.version.outputs.version }}"
86+
git push
87+
88+
- name: Summary
89+
run: |
90+
echo "## CLI Package Published 📦" >> "$GITHUB_STEP_SUMMARY"
91+
echo "" >> "$GITHUB_STEP_SUMMARY"
92+
echo "- **Version:** v${{ steps.version.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
93+
echo "- **Bump:** ${{ inputs.version_bump }}" >> "$GITHUB_STEP_SUMMARY"
94+
echo "- **Dry run:** ${{ inputs.dry_run }}" >> "$GITHUB_STEP_SUMMARY"
95+
echo "" >> "$GITHUB_STEP_SUMMARY"
96+
if [ "${{ inputs.dry_run }}" = "false" ]; then
97+
echo "Install with: \`npx copilot-token-tracker-cli\`" >> "$GITHUB_STEP_SUMMARY"
98+
fi

‎README.md‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,22 @@
11
# GitHub Copilot Token Tracker
22

3-
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.
3+
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.
44

5-
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.
5+
## Supported AI engineering tools:
66

7-
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).
7+
- VS Code + GitHub Copilot
8+
- VS Code Insiders + GitHub Copilot
9+
- GitHub Copilot CLI
10+
- OpenCode + GitHub Copilot (not tested with other AI tooling)
11+
12+
### CLI
13+
14+
We also added a CLI that you can run as an npx package:
15+
```bash
16+
npx copilot-token-tracker usage
17+
```
18+
19+
For screenshots and examples of the CLI output, see the [CLI README](cli/README.md).
820

921
## Features
1022

‎cli/.npmignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
src/
2+
tsconfig.json
3+
esbuild.js
4+
node_modules/
5+
*.ts
6+
*.map

‎cli/README.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Copilot Token Tracker CLI
2+
3+
Command-line interface for analyzing GitHub Copilot token usage from local session files. Works anywhere Copilot Chat stores its session data.
4+
5+
## Quick Start
6+
7+
```bash
8+
# Run directly with npx (no install required)
9+
npx copilot-token-tracker-cli stats
10+
11+
# Or install globally
12+
npm install -g copilot-token-tracker-cli
13+
copilot-token-tracker stats
14+
```
15+
16+
## Commands
17+
18+
### `stats` - Session Overview
19+
20+
Show discovered session files, sessions, chat turns, and token counts.
21+
22+
```bash
23+
copilot-token-tracker stats
24+
copilot-token-tracker stats --verbose # Show per-folder breakdown
25+
```
26+
27+
![Terminal Statistics](../docs/images/Terminal%20Statistics.png)
28+
29+
### `usage` - Token Usage Report
30+
31+
Show token usage broken down by time period.
32+
33+
```bash
34+
copilot-token-tracker usage
35+
copilot-token-tracker usage --models # Show per-model breakdown
36+
copilot-token-tracker usage --cost # Show estimated cost
37+
```
38+
39+
![Terminal Usage](../docs/images/Terminal%20Usage.png)
40+
41+
### `environmental` - Environmental Impact
42+
43+
Show environmental impact of your Copilot usage (CO₂ emissions, water usage, tree equivalents).
44+
45+
```bash
46+
copilot-token-tracker environmental
47+
copilot-token-tracker env # Short alias
48+
```
49+
50+
### `fluency` - Fluency Score
51+
52+
Show your Copilot Fluency Score across multiple categories (Prompt Engineering, Context Engineering, Agentic, Tool Usage, Customization, Team Collaboration).
53+
54+
```bash
55+
copilot-token-tracker fluency
56+
copilot-token-tracker fluency --tips # Show improvement tips, if there are any
57+
```
58+
59+
### `diagnostics` - Search Locations & Stats
60+
61+
Show all locations searched for session files, whether each path exists, and per-location stats (files, sessions, chat turns, tokens).
62+
63+
```bash
64+
copilot-token-tracker diagnostics
65+
```
66+
67+
![Terminal Diagnostics](../docs/images/Terminal%20Diagnostitcs.png)
68+
69+
## Data Sources
70+
71+
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:
72+
73+
- **VS Code** (Stable, Insiders, Exploration) workspace and global storage
74+
- **VSCodium** and **Cursor** editor sessions
75+
- **VS Code Remote** / Codespaces sessions
76+
- **Copilot CLI** agent mode sessions
77+
- **OpenCode** sessions (JSON and SQLite)
78+
79+
## Development
80+
81+
```bash
82+
# From the repository root
83+
npm run cli:build # Build the CLI
84+
npm run cli:stats # Run stats command
85+
npm run cli:usage # Run usage command
86+
npm run cli:environmental # Run environmental command
87+
npm run cli:fluency # Run fluency command
88+
npm run cli:diagnostics # Run diagnostics command
89+
npm run cli -- --help # Run any CLI command
90+
```
91+
92+
## Requirements
93+
94+
- Node.js 18 or later
95+
- GitHub Copilot Chat session files on the local machine
96+
97+
## License
98+
99+
MIT - See [LICENSE](../LICENSE) for details.

0 commit comments

Comments
 (0)