acommons

name	acommons
description	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.
license	MIT
compatibility	Requires Node.js 20+. Works with Claude Code, Cursor, Windsurf, Cline, and other AI agents.
metadata	{"author":"phlegonlabs","version":"1.0"}

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:

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

1. Read ~/.claude/stats-cache.json → dailyActivity array (each has date, messageCount, sessionCount)
2. Read ~/.claude/stats-cache.json → dailyModelTokens array (each has date, tokensByModel)
3. Also read Claude ledger for more accurate daily totals if available
4. 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:

1. Read ~/.claude/stats-cache.json → modelUsage object (keyed by model name, each has inputTokens, outputTokens, cacheReadInputTokens, cacheCreationInputTokens)
2. Read Claude ledger → dailyByModel → aggregate all dates per model
3. Read Codex ledger → aggregate per [provider, model]
4. 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:

1. Aggregate all data sources
2. 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:

1. Create ~/.agentic-commons/ directory
2. Copy <skill_dir>/scripts/hook.mjs → ~/.agentic-commons/hook.mjs
3. Copy <skill_dir>/scripts/collect.mjs → ~/.agentic-commons/collect.mjs
4. 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)
5. 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:

1. Read or create device secret from ~/.agentic-commons/device-secret.key (64-char hex)
2. Build device identity (hostname, platform, arch, cpu/memory info)
3. POST to https://api.agenticcommons.xyz/v1/auth/device/start:

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

4. Show the user: verification URL and user code
5. Open browser to verification_uri_complete
6. Poll POST /v1/auth/device/poll with { "device_code": "..." } every N seconds
7. On "authorized": save access_token to ~/.agentic-commons/api-token.secret
8. 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:

1. ~/.agentic-commons/ directory exists and permissions are 700
2. ~/.agentic-commons/config.json exists, show lastSetup date
3. ~/.agentic-commons/api-token.secret exists (linked status)
4. ~/.claude/settings.json has acommons Stop hook configured
5. Scheduler installed (check schtasks/launchd/crontab)
6. ~/.claude/stats-cache.json readable (Claude Code detected)
7. ~/.codex/sessions/ exists (Codex CLI detected)
8. ~/.local/share/opencode/opencode.db exists (OpenCode detected)
9. ~/.gemini/tmp/ exists (Gemini CLI detected)
10. ~/.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:

1. Collect all available data (same as stats + daily + models)
2. Generate a self-contained HTML file at ~/.agentic-commons/report.html
3. Include: daily chart, model breakdown table, source summary
4. 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.