@gajae-code/stats

中文文档
0.21.0发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 6727

Local observability dashboard for pi AI usage statistics

原始使用文档
文档目录17 节
  1. Features
  2. Metrics Tracked
  3. Usage
  4. Via CLI
  5. Programmatic
  6. API Endpoints
  7. Local server security
  8. Data Storage
  9. Dashboard
  10. Tips & Common Patterns
  11. Sync and print a summary
  12. JSON output for scripting
  13. Dashboard on a custom port
  14. Programmatic: highest-cost folder
  15. Programmatic: most-requested model
  16. Troubleshooting
  17. License

@gajae-code/stats

Local observability dashboard for AI usage statistics.

Features

  • Session log parsing: Reads JSONL session logs from ~/.gjc/agent/sessions/
  • SQLite aggregation: Efficient stats storage and querying using bun:sqlite
  • Web dashboard: Real-time metrics visualization with Chart.js
  • Incremental sync: Only processes new/modified log entries
  • Role usage breakdown: gjc stats --summary and JSON report usage by default, executor, planner, architect, and critic; custom roles and legacy sessions without identity metadata are grouped as other or unknown

Metrics Tracked

MetricCalculation
Tokens/soutput_tokens / (duration / 1000)
Cache Ratecache_read / (input + cache_read) * 100
Error Ratecount(stopReason=error) / total_calls * 100
Total CostSum of usage.cost.total
Avg LatencyMean of duration
TTFTMean of ttft (time to first token)

Usage

Via CLI

# Start dashboard server (default: http://localhost:3847)
gjc stats

# Custom port
gjc stats --port 8080

# Print summary to console
gjc stats --summary

# Output as JSON (for scripting)
gjc stats --json

Programmatic

import { getDashboardStats, syncAllSessions } from "@gajae-code/stats";

// Sync session logs to database
const { processed, files } = await syncAllSessions();

// Get aggregated stats
const stats = await getDashboardStats();
console.log(stats.overall.totalCost);
console.log(stats.byModel[0].avgTokensPerSecond);
console.log(stats.byAgent.find(agent => agent.agent === "executor")?.totalCost);

API Endpoints

Endpoints marked range accept ?range=1h|24h|7d|30d|90d|all (default 24h; an unknown value falls back to 24h). Time series use hourly buckets for 1h and 24h and daily buckets for longer ranges.

EndpointDescription
GET /api/statsThe full DashboardStats object: overall, failures, per-model/folder/agent breakdowns, the time, model, model-performance, and cost series, and the cache-miss attribution (range)
GET /api/stats/overviewoverall and timeSeries only (range)
GET /api/stats/modelsPer-model statistics, ordered by request count (range)
GET /api/stats/model-dashboardbyModel, modelSeries, and modelPerformanceSeries (range)
GET /api/stats/foldersPer-folder/project statistics (range)
GET /api/stats/timeseriesRequests, errors, tokens, and cost per time bucket (range)
GET /api/stats/costsDaily cost per model and provider, split into input/output/cache (range)
GET /api/stats/behaviorUser-message behavior signals (yelling, profanity, repetition, and others): overall, per model, and over time (range)
GET /api/stats/recentMost recent requests, newest first (?limit=, default 100)
GET /api/stats/errorsMost recent requests that stopped with an error (?limit=, default 100)
GET /api/request/:idOne request with its stored messages and output; 404 if unknown
POST /api/syncSync session files and return { processed, files, totalMessages }; 409 while a sync is already running

Local server security

The dashboard binds only to 127.0.0.1; the CLI opens its default browser URL through localhost. API requests must use HTTP, the server's actual port, and exactly localhost or 127.0.0.1. Browser requests must remain same-origin, and session sync requires a same-origin POST request. The server does not enable cross-origin access or trust forwarded host headers.

Reverse-proxy and non-loopback deployments are unsupported. They require a separate authenticated deployment boundary rather than relaxing these local-only checks.

Data Storage

  • Session logs: ~/.gjc/agent/sessions/ (JSONL files)
  • Stats database: ~/.gjc/stats.db (SQLite)

Dashboard

The web dashboard provides:

  • Overall metrics cards (requests, cost, cache rate, error rate, duration, tokens/s)
  • Time series chart showing requests and errors over time
  • Per-model breakdown table
  • Per-folder breakdown table
  • Auto-refresh every 30 seconds

Tips & Common Patterns

Sync and print a summary

Every gjc stats invocation syncs session files before it does anything else, so there is no separate sync flag.

gjc stats --summary

JSON output for scripting

With --json, stdout carries only the JSON document; the sync progress and the Synced N new entries ... summary go to stderr.

gjc stats --json | jq '.overall.totalCost'

Dashboard on a custom port

gjc stats --port 3000

--summary and --json print and exit without starting the server, so --port has no effect when combined with them.

Programmatic: highest-cost folder

import { getDashboardStats, syncAllSessions } from "@gajae-code/stats";

await syncAllSessions();
const stats = await getDashboardStats();

const [first, ...rest] = stats.byFolder;
if (first) {
  const topFolder = rest.reduce((a, b) => (b.totalCost > a.totalCost ? b : a), first);
  console.log(`Highest cost folder: ${topFolder.folder} ($${topFolder.totalCost.toFixed(2)})`);
} else {
  console.log("No folder data available");
}

Programmatic: most-requested model

import { getDashboardStats, syncAllSessions } from "@gajae-code/stats";

await syncAllSessions();
const stats = await getDashboardStats();

// byModel is ordered by request count, highest first.
const topModel = stats.byModel[0];
if (topModel) {
  console.log(`Most requested model: ${topModel.model} (${topModel.totalRequests} requests)`);
}

Troubleshooting

  • No data shown? Check that session logs exist under ~/.gjc/agent/sessions/ (~/<GJC_CONFIG_DIR>/agent/sessions/ if that variable is set). With a custom GJC_CODING_AGENT_DIR, sessions are in $GJC_CODING_AGENT_DIR/sessions/. Otherwise, on Linux and macOS, if XDG_DATA_HOME is set and $XDG_DATA_HOME/gjc exists (created by gjc config init-xdg), sessions are in $XDG_DATA_HOME/gjc/sessions/. These variables must come from your shell environment. A project .env cannot set them, and if the .env entry uses $ expansion it blocks the shell value as well; in both cases the default path applies.
  • Dashboard not starting? Check that port 3847 (or the port passed to --port) is free.

License

MIT

版本与发布记录

@gajae-code/stats 共发布 158 个版本,首次发布于 2026/05/28;过去 12 个月发布了 158 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.21.0latest2026/11/16今天
0.20.1-nightly.20261108030927.43711868338.gb4127889c4a8nightly2026/11/15今天
0.20.1-nightly.20261108030927.43590872198.gb4127889c4a82026/11/141 天前
0.20.1-nightly.20261108030927.43424588966.gb4127889c4a82026/11/132 天前
0.20.1-nightly.20261108030927.43222623203.gb4127889c4a82026/11/123 天前
0.20.1-nightly.20261108030927.43016219422.gb4127889c4a82026/11/114 天前

关于 @gajae-code/stats 的常见问题

@gajae-code/stats 是什么?

Local observability dashboard for pi AI usage statistics

如何安装 @gajae-code/stats?

在项目目录运行 npm install @gajae-code/stats,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gjc-stats,可以用 npx gjc-stats 直接运行。

@gajae-code/stats 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gajae-code/stats 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gajae-code/stats 可以商用吗?

@gajae-code/stats 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gajae-code/stats 的下载量有多少?

根据 npm 官方下载统计,@gajae-code/stats 在 2026/10/16 – 2026/11/14 这 30 天内被下载 6,727 次,日均约 224 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gajae-code/stats 还在维护吗?

最新版本 0.21.0 发布于 2026/11/16(今天);至今共发布 158 个版本,其中过去 12 个月发布了 158 个;首次发布于 2026/05/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。