ai-token-usage-lite 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026
+
+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.
+
+This project includes parser and integration design derived from Token Tracker
+(https://github.com/mm7894215/TokenTracker), MIT licensed.
+
+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,106 @@
+# AI Token Usage Lite
+
+本地版 AI 对话 Token 用量看板。当前支持 Codex、Claude Code 的用量统计，并提供按轮次的 Skills、耗时和 Token 明细。
+
+要求：
+
+- Node.js `>= 20`
+- 本机已安装并使用过 Codex 或 Claude Code
+- 仅扫描本地日志，不请求外部用量 API
+
+## 通过 npx 使用
+
+```bash
+npx ai-token-usage-lite@latest serve --port 7790
+```
+
+打开看板：
+
+```text
+http://127.0.0.1:7790
+```
+
+常用命令：
+
+```bash
+npx ai-token-usage-lite@latest sync
+npx ai-token-usage-lite@latest serve --port 7790
+npx ai-token-usage-lite@latest status --json
+npx ai-token-usage-lite@latest doctor
+npx ai-token-usage-lite@latest export --format csv
+```
+
+默认数据来源：
+
+- Claude Code：`~/.claude/projects`
+- Codex：`~/.codex/sessions`
+- 聚合结果：`~/.ai-token-usage-lite/usage.json`
+
+## 团队内推荐用法
+
+```bash
+npx ai-token-usage-lite@latest serve --port 7790
+```
+
+如果需要只刷新本地聚合结果：
+
+```bash
+npx ai-token-usage-lite@latest sync
+```
+
+如果需要排查为什么没有统计到数据：
+
+```bash
+npx ai-token-usage-lite@latest doctor
+```
+
+## 本地开发与发布检查
+
+```bash
+npm test
+npm run pack:check
+npm run smoke:npx
+npm run release:check
+node bin/ai-token-usage-lite.js sync
+node bin/ai-token-usage-lite.js serve --port 7790
+```
+
+发布到公开 npm：
+
+```bash
+npm login
+npm run release:check
+npm run publish:public
+```
+
+说明：
+
+- 仓库内已固定 npm cache 到 `./.npm-cache`，避免受全局 `~/.npm` 权限问题影响。
+- `smoke:npx` 会先打 tarball，再用 `npm exec --package=<tgz>` 验证公开安装路径对应的 CLI 入口。
+
+## 统计内容
+
+- 总览：消耗总 Token、输入 Token、输出 Token、缓存输入 Token、对话次数。
+- 按来源：Codex、Claude Code 的用量分布。
+- 按模型：不同模型的 Token 和对话次数。
+- 按日期：每日用量趋势。
+- 按项目：从本地日志里能识别到的项目引用。
+- 按 Skills：每个 skill 的调用轮次、总耗时、总 Token、平均 Token、平均耗时。
+- 最近对话轮次：每轮对话的来源、模型、耗时、Skills、输入/输出/缓存/消耗总 Token。
+
+## Token 口径
+
+- 输入 Token：发送给模型的上下文消耗，通常包括你的请求、历史上下文、工具结果、系统提示等。
+- 输出 Token：模型生成回答、工具调用参数、推理输出等产生的消耗。
+- 缓存输入 Token：命中上下文缓存的输入 Token。它仍然属于模型上下文规模，但计费口径通常会和普通输入不同，具体以各工具或模型服务商为准。
+- 消耗总 Token：当前看板主口径，按 `输入 - 缓存输入 + 输出 + cache creation` 计算，更接近实际消耗。
+
+## Skills 识别说明
+
+- Skill 识别分为：
+  - `explicit`：对话文本中明确出现正在使用某个 skill。
+  - `inferred`：从读取 `SKILL.md` 等本地 skill 文件路径推断。
+
+## 隐私边界
+
+工具只落地聚合后的统计信息：来源、模型、时间桶、项目引用、Token 数、轮次耗时和 Skill 名称。不会保存 prompt、assistant response、工具调用参数、工具结果或文件内容，也不会请求外部用量 API。

package/bin/ai-token-usage-lite.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { run } = require("../src/cli");
+
+run(process.argv.slice(2)).catch((err) => {
+  process.stderr.write(`${err && err.stack ? err.stack : String(err)}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ai-token-usage-lite",
+  "version": "0.1.0",
+  "description": "Local-only token usage dashboard for Codex and Claude Code.",
+  "type": "commonjs",
+  "author": "lingaibo",
+  "homepage": "https://www.npmjs.com/package/ai-token-usage-lite",
+  "bin": {
+    "ai-token-usage-lite": "bin/ai-token-usage-lite.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "public/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run --cache ./.npm-cache",
+    "smoke:npx": "node scripts/release-smoke.js",
+    "release:check": "npm test && npm run pack:check && npm run smoke:npx",
+    "publish:public": "npm publish --access public --cache ./.npm-cache"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "ai",
+    "token",
+    "usage",
+    "dashboard",
+    "codex",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}