Acommons

Skill Phlegonlabs/agentic-commons/skills/acommons

AI coding tool usage analytics. Tracks token usage across Claude Code, Codex CLI, OpenCode, Gemini CLI, and external tools. Use when user wants to view AI usage stats, sync usage data, or set up automatic usage tracking.From its SKILL.md

Install

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

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

11.0 KB, ~3.0k tokens by cl100k_base, as published. Nobody here has run it

acommons — AI Usage Analytics Skill

You are an AI agent with access to local AI tool usage data. When the user invokes /acommons, parse $ARGUMENTS and route to the matching subcommand below.

Default subcommand: stats (when no argument given)

Environment

DATA_DIR = ~/.agentic-commons
CLAUDE_STATS = ~/.claude/stats-cache.json
CLAUDE_LEDGER = ~/.agentic-commons/claude-ledger.json
CODEX_SESSIONS = ~/.codex/sessions/
CODEX_LEDGER = ~/.agentic-commons/codex-ledger.json
OPENCODE_DB = ~/.local/share/opencode/opencode.db
GEMINI_SESSIONS = ~/.gemini/tmp/*/chats/session-*.json
EXTERNAL_USAGE = ~/.agentic-commons/external-usage/

On Windows: ~/.opencode → ~/AppData/Roaming/opencode

Subcommand: `stats` (default)

Show today's AI tool usage in a table.

Steps:

Read ~/.claude/stats-cache.json → extract today from dailyActivity (messages, sessions, toolCalls) and dailyModelTokens (tokensByModel sum)
Check ~/.agentic-commons/claude-ledger.json → if it has today's entry, sum all models' totalIO for a more accurate token count
Check ~/.codex/sessions/ → count .jsonl files as sessions. For token total: prefer ~/.agentic-commons/codex-ledger.json if exists, otherwise count files
Check ~/.local/share/opencode/opencode.db → if exists, report "detected" (reading SQLite requires the collect script)
Check ~/.gemini/tmp/ → count session-*.json files
Check ~/.agentic-commons/external-usage/ → count .jsonl files

Output format:

AI Tool Usage — Today (YYYY-MM-DD)

Tool          Sessions  Messages  IO Tokens   Tool Calls
────────────  ────────  ────────  ──────────  ──────────
Claude Code         3        42    130.0K         120
Codex CLI           5        --     89.2K          --
OpenCode            2        --     45.1K          --
Gemini CLI          1        --     12.3K          --
────────────  ────────  ────────  ──────────  ──────────
Total              11        42    276.6K         120

Format numbers: 1,234 for small, 12.3K for thousands, 1.5M for millions.

Subcommand: `daily`

Show 14-day daily breakdown.

Steps:

Read ~/.claude/stats-cache.json → dailyActivity array (each has date, messageCount, sessionCount)
Read ~/.claude/stats-cache.json → dailyModelTokens array (each has date, tokensByModel)
Also read Claude ledger for more accurate daily totals if available
For other tools: read their respective data sources and group by date

Output format:

Daily Usage — Last 14 Days

Date        Claude    Codex    OpenCode  Gemini   Total
──────────  ────────  ───────  ────────  ───────  ────────
2025-01-15   130.0K    89.2K    45.1K    12.3K   276.6K
2025-01-14    95.0K    72.1K    38.0K     8.1K   213.2K
...

Subcommand: `models`

Show per-model token usage aggregated across all time.

Steps:

Read ~/.claude/stats-cache.json → modelUsage object (keyed by model name, each has inputTokens, outputTokens, cacheReadInputTokens, cacheCreationInputTokens)
Read Claude ledger → dailyByModel → aggregate all dates per model
Read Codex ledger → aggregate per [provider, model]
Read other sources as available

Output format:

Token Usage by Model

Source       Model                          Input     Output    Cached     Total IO
───────────  ─────────────────────────────  ────────  ────────  ─────────  ────────
Claude       claude-sonnet-4-20250514         80.0K    50.0K    230.0K    130.0K
Claude       claude-haiku-4-5-20251001        20.0K    10.0K     50.0K     30.0K
Codex        gpt-4o                           60.0K    29.2K     15.0K     89.2K
OpenCode     claude-sonnet-4-20250514         30.0K    15.1K     40.0K     45.1K
Gemini       gemini-2.5-pro                    8.0K     4.3K      6.0K     12.3K

Subcommand: `total`

Show all-time aggregated summary.

Steps:

Aggregate all data sources
Sum by source (claude, codex, opencode, gemini, external)

Output:

All-Time Usage Summary

Source       Days   Sessions   IO Tokens    Cached Tokens
───────────  ─────  ─────────  ───────────  ─────────────
Claude          45       150      4.5M          12.3M
Codex           30        89      2.1M           0.3M
OpenCode        20        45      0.9M           0.4M
Gemini          10        25      0.3M           0.1M
External         5        --      0.1M              0
───────────  ─────  ─────────  ───────────  ─────────────
Total           45       309      7.9M          13.1M

Subcommand: `sync`

Run the full collect + upload pipeline.

Action: Execute the collect script:

node ~/.agentic-commons/collect.mjs

If ~/.agentic-commons/collect.mjs does not exist, tell the user to run /acommons setup first.

Show the script output to the user.

Subcommand: `setup`

First-time setup: install hook, scheduler, and copy scripts.

Action: Execute the setup script:

bash <skill_dir>/scripts/setup.sh

Where <skill_dir> is the directory containing this SKILL.md file.

If on Windows and bash is not available, run the steps manually:

Create ~/.agentic-commons/ directory
Copy <skill_dir>/scripts/hook.mjs → ~/.agentic-commons/hook.mjs
Copy <skill_dir>/scripts/collect.mjs → ~/.agentic-commons/collect.mjs

Install Claude Code Stop Hook by modifying ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "node ~/.agentic-commons/hook.mjs" }] }
    ]
  }
}

(Merge with existing hooks, don't overwrite)

Install hourly scheduler:
- Windows: schtasks /create /tn "AgenticCommons" /tr "wscript.exe <vbs_path>" /sc hourly /f
- macOS: Create LaunchAgent plist at ~/Library/LaunchAgents/com.agentic-commons.plist
- Linux: Add crontab entry 0 * * * * node ~/.agentic-commons/collect.mjs

After setup, suggest the user run /acommons link to connect their account.

Subcommand: `link`

Device OAuth authentication flow.

Steps:

Read or create device secret from ~/.agentic-commons/device-secret.key (64-char hex)
Build device identity (hostname, platform, arch, cpu/memory info)

POST to https://api.agenticcommons.xyz/v1/auth/device/start:

{ "device_label": "<hostname>", "device_secret": "<hex>", "device_profile": {...} }

Show the user: verification URL and user code
Open browser to verification_uri_complete
Poll POST /v1/auth/device/poll with { "device_code": "..." } every N seconds
On "authorized": save access_token to ~/.agentic-commons/api-token.secret
Update ~/.agentic-commons/config.json with linkedAt and deviceLabel

Note: On Windows, the token is encrypted with PowerShell SecureString before saving.

Subcommand: `doctor`

Health check and diagnostics.

Check each item and report status:

~/.agentic-commons/ directory exists and permissions are 700
~/.agentic-commons/config.json exists, show lastSetup date
~/.agentic-commons/api-token.secret exists (linked status)
~/.claude/settings.json has acommons Stop hook configured
Scheduler installed (check schtasks/launchd/crontab)
~/.claude/stats-cache.json readable (Claude Code detected)
~/.codex/sessions/ exists (Codex CLI detected)
~/.local/share/opencode/opencode.db exists (OpenCode detected)
~/.gemini/tmp/ exists (Gemini CLI detected)
~/.agentic-commons/upload-tracker.json — last upload info

Output format:

acommons Doctor

  ✓ Data directory exists (~/.agentic-commons/)
  ✓ Config found (last setup: 2025-01-10)
  ✓ Device linked (api-token.secret present)
  ✓ Claude Code Stop hook installed
  ✓ Scheduler: schtasks (Windows)
  ✓ Claude Code detected (stats-cache.json readable)
  ✗ Codex CLI not found
  ✓ OpenCode detected (opencode.db readable)
  ✗ Gemini CLI not found
  ✓ Last upload: 2025-01-15 (42 payloads)

Subcommand: `probe`

Detect all installed AI coding tools (not just data sources).

Scan for these tools:

Tool	Config Dir	Binary	Provider
Claude Code	~/.claude	claude	anthropic
Codex CLI	~/.codex	codex	openai
Gemini CLI	~/.gemini	gemini	google
Kimi CLI	~/.kimi	kimi	moonshot
OpenCode	~/.opencode	opencode	various
Cursor	~/.cursor	cursor	various
Windsurf	~/.codeium	windsurf	codeium
Aider	~/.aider	aider	various
Goose	~/.config/goose	goose	various
Amp	~/.config/amp	amp	sourcegraph
Droid	~/.factory	droid	factory
Kiro	~/.kiro	kiro-cli	aws
Copilot CLI	~/.copilot	copilot	github
Cody	~/.config/sourcegraph	cody	sourcegraph

For each: check if config directory exists AND/OR if binary is on PATH (use which/where).

Output:

AI Tool Probe

Tool           Binary  Config  Provider
─────────────  ──────  ──────  ──────────
Claude Code    yes     yes     anthropic
Codex CLI      yes     yes     openai
OpenCode       yes     yes     various
Gemini CLI     yes     yes     google
Cursor         yes     no      various

5 detected, 9 not found

Subcommand: `report`

Generate an HTML usage report.

Steps:

Collect all available data (same as stats + daily + models)
Generate a self-contained HTML file at ~/.agentic-commons/report.html
Include: daily chart, model breakdown table, source summary
Open in browser

Notes for AI Agents

All data is LOCAL. No API calls needed for stats, daily, models, total, probe, doctor.
Only sync, link, and setup perform network/system operations.
Token formatting: use K for thousands, M for millions (e.g., 130.0K, 1.5M).
The total_io field equals input_uncached + output — it does NOT include cached tokens.
When reading JSON files, always handle missing/malformed files gracefully.
Refer to references/data-sources.md for detailed data format documentation.

What ships with it: 4 files

43.2 KB alongside SKILL.md, 3 of them executable

references/

data-sources.md5.1 KB

scripts/

collect.mjsruns20.5 KB
hook.mjsruns13.3 KB
setup.shruns4.2 KB

One thing to look at

What its file declares

SKILL.md

acommons — AI Usage Analytics Skill

Environment

Subcommand: stats (default)

Subcommand: daily

Subcommand: models

Subcommand: total

Subcommand: sync

Subcommand: setup

Subcommand: link

Subcommand: doctor

Subcommand: probe

Subcommand: report

Notes for AI Agents

What ships with it: 4 files

references/

scripts/

Keep looking

Subcommand: `stats` (default)

Subcommand: `daily`

Subcommand: `models`

Subcommand: `total`

Subcommand: `sync`

Subcommand: `setup`

Subcommand: `link`

Subcommand: `doctor`

Subcommand: `probe`

Subcommand: `report`