Agentic Commons

Private-by-design AI usage analytics for coding tools

Track token usage across Claude Code, Codex CLI, OpenCode, Gemini CLI, and more.
Local-first collection, verifiable aggregation, optional cloud sync.
Your prompts never leave your machine.

     

English | 简体中文 | 繁體中文

---

📑 Quick Navigation

Section	Description
Quick Start	Install in 2 minutes
CLI Commands	Full command reference
Claude Code Skill	Use inside Claude Code directly
Supported Tools	Claude, Codex, Gemini, and more
Privacy Boundary	What's uploaded vs. what stays local
External CLI Import	Feed usage from any tool
Local Development	Build from source

---

🚀 Quick Start

macOS / Linux:

npm i -g agentic-commons
acommons setup
acommons doctor

Windows:

npm i -g agentic-commons
acommons setup
acommons doctor

After setup, automatic sync is enabled (launchd hourly on macOS, schtasks on Windows, crontab on Linux).

Manual sync (optional):

acommons sync

Requirements: Node.js >= 20, npm >= 10

---

🛠 CLI Commands

Command	Description
acommons setup	First-time setup (hook, scheduler, scripts)
acommons doctor	Health check and diagnostics
acommons sync	Collect + upload pipeline
acommons stats	Today's usage summary
acommons daily	14-day daily breakdown
acommons models	Per-model token usage
acommons total	All-time aggregated summary
acommons report	Generate HTML usage report
acommons watch	Watch mode
acommons link	Device OAuth authentication
acommons update	Update to latest version

---

🎯 Claude Code Skill

No CLI install required — use /acommons directly inside Claude Code.

SKILL

npx skills add Phlegonlabs/agentic-commons --skill acommons -g -y

then type /acommons in Claude Code

The skill reads local data directly and includes a Stop hook for automatic token ledger updates on session end.

All skill commands

Command	Description
/acommons	Show today's usage (default: stats)
/acommons daily	14-day daily breakdown
/acommons models	Per-model token usage
/acommons total	All-time summary
/acommons sync	Run collect + upload pipeline
/acommons setup	First-time setup
/acommons link	Device OAuth authentication
/acommons doctor	Health check and diagnostics
/acommons probe	Detect all installed AI tools
/acommons report	Generate HTML usage report

---

🤖 Supported Tools

Tool	Config Dir	Data Source	Status
Claude Code	~/.claude	stats-cache.json + ledger	Full
Codex CLI	~/.codex	sessions/*.jsonl + ledger	Full
OpenCode	~/.local/share/opencode	opencode.db	Full
Gemini CLI	~/.gemini	session-*.json	Full
Cursor	~/.cursor	Probe detection	Detect
Windsurf	~/.codeium	Probe detection	Detect
Aider	~/.aider	Probe detection	Detect
Goose	~/.config/goose	Probe detection	Detect
Amp	~/.config/amp	Probe detection	Detect
Kimi CLI	~/.kimi	Probe detection	Detect
Kiro	~/.kiro	Probe detection	Detect
External	~/.agentic-commons/external-usage/	*.jsonl drop-in	Full

Full = token-level analytics. Detect = acommons probe recognizes the tool.

---

🔒 Privacy Boundary

Your prompts never leave your machine. Only aggregated stats are uploaded.

Uploaded	Never Uploaded
date, source, model	Prompt / message content
input_uncached, output	Transcript text and reasoning blocks
cached_read, cached_write, total_io	File paths and repository names
	Raw session logs

---

📦 External CLI Auto-Import

Drop event logs into ~/.agentic-commons/external-usage/*.jsonl and acommons sync will auto-scan and aggregate them.

Minimal event shape:

{
  "timestamp": "2026-02-19T16:55:00Z",
  "source": "opencode",
  "provider": "openai",
  "model": "gpt-5.1-codex-mini",
  "usage": { "prompt_tokens": 1200, "completion_tokens": 320 }
}

Also accepted field formats

Format	Fields
Normalized	input_uncached, output, cached_read, cached_write
Anthropic	input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens
Gemini	usageMetadata.promptTokenCount, usageMetadata.candidatesTokenCount

Quick test:

mkdir -p ~/.agentic-commons/external-usage
cat >> ~/.agentic-commons/external-usage/opencode.jsonl <<'JSON'
{"timestamp":"2026-02-19T17:20:00Z","source":"opencode","provider":"openai","model":"gpt-5.1-codex-mini","usage":{"prompt_tokens":1200,"completion_tokens":300}}
JSON
acommons doctor   # verify detection
acommons sync     # upload

---

🔧 Local Development

git clone https://github.com/Phlegonlabs/agentic-commons.git
cd agentic-commons
npm install
npm run build:cli
npm run typecheck -w @agentic-commons/shared

---

📞 Support

Channel	Link
Usage Questions	GitHub Issues
Feature Requests	GitHub Issues
Security Reports	GitHub Security Advisories (private)

---

MIT License · Phlegonlabs — Private-by-design AI usage analytics