Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
"name": "command-code-usage",
"description": "See your Command Code plan usage (5-hour and weekly rolling windows, monthly credits or balance) from inside your coding agent, with a remaining-requests estimate. Requires a Command Code plan.",
"owner": {
"name": "Jovan1666"
},
"plugins": [
{
"name": "command-code-usage",
"source": "./command-code-usage",
"version": "1.3.2",
"description": "See your Command Code plan usage — 5-hour and weekly rolling windows, monthly credits or balance — right inside the conversation, with a remaining-requests estimate and a burn-rate warning. Requires a Command Code plan.",
"displayName": "Command Code Usage",
"category": "utilities",
"homepage": "https://github.com/Jovan1666/zcode-command-code-usage",
"author": {
"name": "Jovan1666",
"url": "https://github.com/Jovan1666"
}
}
]
}
10 changes: 10 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# 仓库内统一 LF,避免 Windows/macOS/Linux 之间换行符抖动。
# 本项目的 Markdown(含 frontmatter)、JSON 与 Node 脚本都按 LF 处理。
* text=auto eol=lf

*.png binary
*.jpg binary
*.ico binary
*.gif binary
*.woff binary
*.woff2 binary
85 changes: 85 additions & 0 deletions .github/workflows/check.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
name: Check

on:
push:
branches: [main]
pull_request:
workflow_dispatch:

permissions:
contents: read

jobs:
check:
# 三平台矩阵 × 双 Node:插件声称跨平台、且只用内置模块,就必须真的验过。
# 本地只在 Windows 上验证过,Linux 与 macOS 由这里覆盖。
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
node: ['18', '22']
runs-on: ${{ matrix.os }}
steps:
# action 固定到提交哈希,不用可变的 major 标签:标签会指向新的提交,
# 那等于让第三方随时改我 CI 里跑的东西。
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0

- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
with:
node-version: ${{ matrix.node }}

- name: 发布检查(清单一致性 / 版本 / 命名规则 / 密钥与个人路径 / serve)
run: node scripts/check.mjs

- name: 离线功能冒烟测试(六种输出模式,--demo 不联网)
shell: bash
run: |
set -e
S=command-code-usage/scripts/cc-usage.mjs
node "$S" --help > /dev/null
node "$S" --demo > /dev/null
node "$S" --demo hot > /dev/null
node "$S" --demo --md > /dev/null
node "$S" --demo --compact > /dev/null
node "$S" --demo --json > /dev/null
echo "全部输出模式通过"

- name: 安装到临时 HOME 并验证命令可被发现
shell: bash
env:
# POSIX 上 Node 读 HOME,Windows 上读 USERPROFILE;两个都设,覆盖两平台。
HOME: ${{ runner.temp }}/fakehome
USERPROFILE: ${{ runner.temp }}/fakehome
run: |
set -e
mkdir -p "$HOME"
node command-code-usage/scripts/install-user-scope.mjs
node command-code-usage/scripts/verify-discoverable.cjs .

- name: 安装器冲突保护(不得覆盖用户自己的同名文件)
shell: bash
env:
HOME: ${{ runner.temp }}/fakehome2
USERPROFILE: ${{ runner.temp }}/fakehome2
run: |
set -e
mkdir -p "$HOME/.zcode/commands"
echo "我自己的命令" > "$HOME/.zcode/commands/quota.md"
if node command-code-usage/scripts/install-user-scope.mjs; then
echo "::error::安装器在存在同名外部文件时应当中止"
exit 1
fi
grep -q "我自己的命令" "$HOME/.zcode/commands/quota.md"
echo "冲突保护生效:用户文件未被覆盖"

- name: 安装器可卸载
shell: bash
env:
HOME: ${{ runner.temp }}/fakehome
USERPROFILE: ${{ runner.temp }}/fakehome
run: |
set -e
node command-code-usage/scripts/install-user-scope.mjs --uninstall
test ! -e "$HOME/.zcode/commands/quota.md"
test ! -e "$HOME/.zcode/skills/command-code-usage"
echo "卸载干净"
21 changes: 21 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# 依赖与构建产物
node_modules/
package-lock.json
pnpm-lock.yaml
yarn.lock

# 运行本插件生成的产物
command-code-usage.html

# 编辑器 / 系统
.vscode/
.idea/
*.swp
.DS_Store
Thumbs.db
desktop.ini

# 本地临时与调试
*.log
tmp/
.tmp/
124 changes: 124 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
# Changelog

All notable changes to this project are documented here.
This project follows [Semantic Versioning](https://semver.org/).

## [1.3.2] — 2026-09-26

The plugin is maintained here again. This release restores the full plugin into this repository
and merges the changes that were made after it moved into the shared `commandcode-usage` repo.

### Added

- **`--serve`, kept deliberately.** The panel can still be served as a local page
(`node command-code-usage/scripts/cc-usage.mjs --serve`, default port 8787, `--port <n>` to
change it), refreshing every 30 s for ZCode's built-in browser pane — the zero-token way to
watch the numbers.
The shared implementation dropped its top-level `node:http` import to save startup time,
because in hosts that run the script once per message that cost is paid on every turn. This
plugin is not one of those: `/quota` and `/usage` run only when you ask for them, so startup
cost is not a reason to lose the feature. It is now resolved **lazily**, inside `serve()`,
with the `createRequire` the script already had — so every other mode keeps the faster start
and `--serve` still works.
- **`SECURITY.md`** — what the plugin reads, writes and sends, and how to report a problem
privately.
- **`docs/FINDINGS.md`** — the shared implementation's cross-host research notes, carried here
because this repository now owns its own copy of the implementation.

### Changed

- **`cc-usage.mjs` is now the current shared implementation** (2101 lines) with this
repository's `--serve` on top, instead of the older 1380-line revision. The visible
consequences:
- **Faster startup.** Internal modules load through `createRequire` rather than ESM static
imports, about 11 ms less per run.
- **A corrected plan table.** Pro is $80 (the `individual-pro-v1` alias is kept so older
accounts still resolve), `Max 10x` / `Max 20x` and their aliases are recognised, and
Provider is treated as pay-as-you-go. Window caps still come from the API; the table is only
a fallback for the monthly total.
- **Wider credential discovery.** After the environment, `~/.commandcode/auth.json` and
`~/.zcode/v2/provider_config.json`, the script also reads the provider configs other agent
tools leave behind — so a machine that has already used Command Code elsewhere needs no
second login. The key still only ever goes into an `Authorization: Bearer` header.
- **`--html --open` and `--serve --open` are safer.** The opener is invoked with an argv
array instead of a shell command string, so a path containing quotes or `&` can no longer
break the launch.
- The status-line and hook engine, and the local cache under `~/.commandcode-usage/`
(snapshot plus a 24 h model-catalog cache), came with the new base. This plugin's commands
never call those paths — ZCode exposes neither a status-line seat nor a hook output field —
so a `/quota` run still writes nothing.
- **The commands and the skill are the current revisions.** The command body now resolves the
script through `$ZCODE_PLUGIN_ROOT` first and falls back to searching the known agent
directories; the local install route still injects the absolute path, so a user-scope install
keeps working.
- **`scripts/check.mjs` grew the release gate's own suites** — status-line rendering (width
adaptation, never any ANSI), the route decision table, threshold and hook output, the output
formats, and the secret/personal-path scan — on top of the manifest, version, command-parse
and installer checks it already had. It now also asserts `--serve` end to end: a stub API on
loopback, a real server start, one request, and an assertion that the response is the HTML
panel.
- **Version 1.3.2 everywhere** — both plugin manifests, both marketplace catalogues, the
script's `VERSION` constant and this file. `scripts/check.mjs` fails the build if they drift.
- **CI** pins both actions to commit hashes, runs Node 18 and 22 across Ubuntu, Windows and
macOS, and keeps the offline smoke tests for every output mode.
- `verify-discoverable.cjs` no longer reports a missing script path when the command body is
still carrying the install-time placeholder.

## [1.2.0] — 2026-09-21

### Changed
- **`/quota` costs about 43% fewer tokens.** The command body was cut from 731 to 311 characters,
and the agent is now told not to restate the panel — it is already visible from the tool call.
Measured cost per invocation dropped from roughly 680 to 390 tokens.
- Documented the cost, and the zero-token alternative (`--serve` in the built-in browser pane), in
both READMEs.

## [1.1.0] — 2026-09-21

A second manifest family, so the plugin is not tied to one agent's layout.

### Added
- **A `.claude-plugin/` manifest alongside the ZCode one.** The plugin now ships a
`.claude-plugin/plugin.json` next to the ZCode manifest, plus a strict-clean
`.claude-plugin/marketplace.json` that passes the other validator with zero warnings.
- **Cross-platform CI** (`.github/workflows/check.yml`) running on Ubuntu, Windows and macOS: the
release gate, offline smoke tests for every output mode, an install-and-discover check against a
throwaway home directory, and the installer's conflict guard.
- **`scripts/check.mjs`** — a release gate shared by CI and local runs. It compares the duplicated
fields between the ZCode and `.claude-plugin/` manifests, enforces version consistency across all
five places that carry a version, checks the command/skill files against ZCode's actual parsing
rules (name pattern, allowed frontmatter keys, reserved command names), and fails on any leaked
secret or machine-specific path.

### Changed
- The command body's script lookup now searches the known agent directories — `~/.zcode`,
`~/.claude`, `~/.agents`, `~/.codex` — instead of only ZCode's, so the same command works
wherever the plugin was installed from.

## [1.0.0] — 2026-09-21

First public release.

### Added
- `/quota` (and the `/usage` alias): render Command Code usage in the ZCode conversation —
5-hour rolling window, weekly rolling window, monthly allowance or balance.
- A **remaining-requests estimate** derived from the account's own average cost per request, so it
adapts to any plan and any model mix without hard-coded per-model rates.
- A **burn-rate warning** for windows projected to run out before they reset, gated on a minimum
sample (under 5% of the window elapsed draws no conclusion, to avoid false alarms).
- Account-shape handling: known plans, unknown/new/enterprise plans, pay-as-you-go balances,
organisation spend caps, and accounts with no requests yet.
- Output modes: terminal panel, `--md` Markdown table, `--compact` one-liner, `--json` normalised
fields plus raw responses, `--from-json` offline replay, `--demo` sample data.
- Optional HTML dashboard (`--html`, `--serve`) for people who want a big screen.
- `install-user-scope.mjs` — user-scope install, sync and uninstall, with a content-hash based
guard that refuses to overwrite files the user wrote or edited.
- `verify-discoverable.cjs` — diagnostic that re-implements ZCode's own command parser so
discovery problems can be reported with evidence.
- Bilingual documentation (English and Simplified Chinese).

### Notes
- No credentials are stored, printed or committed. The key is resolved at runtime from the
environment, the Command Code CLI auth file, or the provider already configured in ZCode.
- ZCode snapshots its command catalogue at session start, and closing the window may only minimise
it to the tray. Restart the app fully after installing.
Loading
Loading