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:

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.