How do I install the Acommons skill?

Run npx skillmds@latest add phlegonlabs/acommons in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Acommons skill do?

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. It is listed under Data & Analytics on SkillMD.

Is Acommons safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Acommons?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Acommons free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Acommons?

Phlegonlabs (@phlegonlabs) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Acommons by phlegonlabs — Agent Skill

Name: Acommons
Author: Phlegonlabs

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.

Acommons

File contents

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

Frequently asked questions

Acommons

File contents

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

Related skills

Frequently asked questions

How do I install the Acommons skill?

What does the Acommons skill do?

Is Acommons safe to use?

Which AI agents work with Acommons?

Is Acommons free to use?

Who published Acommons?

Subcommand: `stats` (default)

Subcommand: `daily`

Subcommand: `models`

Subcommand: `total`

Subcommand: `sync`

Subcommand: `setup`

Subcommand: `link`

Subcommand: `doctor`

Subcommand: `probe`

Subcommand: `report`