skill

agentic-commons

Privacy-first AI usage analytics across 6+ coding tools. Local-first — your prompts never leave your machine.

Phlegonlabs/agentic-commonscommunitylistedunreviewed

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/Phlegonlabs/agentic-commons itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 27, 2026

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.

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

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

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 }
}

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