opencode-skill-tracker

opencode-skill-tracker

Local-first usage tracking for OpenCode. Records skills, slash commands, tools, and subagent usage in a SQLite database.

Features

• Automatic Tracking: Records every skill invocation, tool call, and command usage from OpenCode
• Zero Network Calls: All data stays local on your machine in a SQLite database
• Rich Metadata: Stores timestamps, arguments, success/failure status, and execution duration
• Privacy First: No telemetry or external services — your usage data never leaves your device
• Query-Friendly: SQLite database can be queried with any SQL tool or programmatically

What Gets Tracked

Event Type	Description	Example
Skills	Built-in and custom skill invocations	brainstorming, investigate
Commands	OpenCode commands and shortcuts	opencode:run, opencode:review
Tools	Tool calls made during sessions	read_file, edit_file
Subagents	Dispatched subagent tasks	fix-bug, refactor-code

Installation

Option 1: Install as npm Package (Recommended)

npm install DKER2/opencode-skill-tracker

This single command:

• Installs the plugin and its dependencies
• Generates the Prisma client
• Creates the SQLite database at ~/.config/opencode-skill-tracker/skill-usage.db
• Applies the database schema

Option 2: Clone and Install

git clone https://github.com/DKER2/opencode-skill-tracker.git
cd opencode-skill-tracker
npm install

Configure OpenCode

Add the tracker to your project's opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "./node_modules/opencode-skill-tracker/dist/src/opencode-plugin.js"
  ]
}

For a global install or custom location, use the absolute path:

{
  "plugin": [
    "/absolute/path/to/opencode-skill-tracker/dist/src/opencode-plugin.js"
  ]
}

Restart OpenCode

The plugin activates on startup and begins tracking immediately.

Verify Installation

npx opencode-skill-tracker db:status

Expected output:

========================================
    OpenCode Skill Tracker REPORT
========================================
Total Sessions Tracked: 0
Total Skill Calls Logged: 0

--- Top Skills Used ---
No usage logged yet! Make some skill calls to start tracking.
========================================

Data Storage

All usage data is stored locally in a SQLite database:

• macOS/Linux: ~/.config/opencode-skill-tracker/skill-usage.db
• Windows: %LOCALAPPDATA%\opencode-skill-tracker\skill-usage.db

Database Schema

The database contains a single skill_calls table:

Column	Type	Description
id	INTEGER	Auto-increment primary key
sessionId	TEXT	Session identifier
eventName	TEXT	Event type (e.g., tool.execute.after)
skillName	TEXT	Name of the skill/tool
args	TEXT	JSON-serialized arguments
durationMs	INTEGER	Execution duration in milliseconds
timestamp	DATETIME	When the event occurred

Example Queries

-- Most used skills today
SELECT skillName, COUNT(*) as count
FROM skill_calls
WHERE date(timestamp) = date('now')
GROUP BY skillName
ORDER BY count DESC;

-- Skill usage in the last 7 days
SELECT skillName, COUNT(*) as count, AVG(durationMs) as avg_duration
FROM skill_calls
WHERE timestamp > datetime('now', '-7 days')
GROUP BY skillName
ORDER BY count DESC;

-- Recent skill calls
SELECT sessionId, eventName, skillName, durationMs, timestamp
FROM skill_calls
ORDER BY timestamp DESC
LIMIT 10;

Usage

CLI Commands

When installed as a package, all commands are available via npx:

# View usage statistics dashboard
npx opencode-skill-tracker db:status

# Open Prisma Studio (GUI database explorer)
npx opencode-skill-tracker db:studio

# Re-initialize database (if needed)
npx opencode-skill-tracker db:init

Viewing Your Data

You can query the SQLite database directly using any SQLite client:

# Using the sqlite3 CLI
sqlite3 ~/.config/opencode-skill-tracker/skill-usage.db "SELECT * FROM skill_calls LIMIT 10;"

# Using a GUI tool like DB Browser for SQLite, TablePlus, or DataGrip

Exporting Data

# Export to CSV
sqlite3 ~/.config/opencode-skill-tracker/skill-usage.db ".mode csv" ".output usage.csv" "SELECT * FROM skill_calls;"

# Export to JSON
sqlite3 ~/.config/opencode-skill-tracker/skill-usage.db ".mode json" ".output usage.json" "SELECT * FROM skill_calls;"

Programmatic Access

import { getPrismaClient } from 'opencode-skill-tracker/dist/src/db.js';

const prisma = getPrismaClient();
const stats = await prisma.skillCall.groupBy({
  by: ['skillName'],
  _count: { skillName: true },
});
console.log(stats);
await prisma.$disconnect();

Development

Prerequisites

• Node.js 20+
• TypeScript 5.x (for development)

Running Tests

npm test

Tests use Node.js native test runner and cover:

• Event normalization
• Database operations
• Stats aggregation

Building from Source

npm run build

Compiles TypeScript (src/) to JavaScript (dist/). The dist/ directory is committed to git so the package works without a build step when installed from GitHub.

Modifying Source

1. Edit files in src/
2. Run npm run build to compile
3. Run npm test to verify
4. Commit both src/ and dist/ changes

Project Structure

opencode-skill-tracker/
├── src/                        # TypeScript source code
│   ├── db.ts                   # Prisma client setup
│   ├── log-skill.ts            # Event logger
│   ├── usage-stats.ts          # Statistics reporter
│   ├── skill-event-normalizer.ts # Event normalization
│   ├── opencode-plugin.ts      # OpenCode plugin entrypoint
│   └── utils.ts                # Shared utility functions
├── dist/                       # Compiled JavaScript (committed for installs)
│   └── src/
│       ├── db.js
│       ├── log-skill.js
│       ├── usage-stats.js
│       ├── skill-event-normalizer.js
│       ├── opencode-plugin.js
│       └── utils.js
├── tests/                      # Test suite
│   ├── skill-event-normalizer.test.ts
│   └── usage-stats-opencode.test.ts
├── prisma/
│   ├── schema.prisma           # Prisma schema definition
│   └── init-db.ts              # Database initialization
├── opencode.json               # OpenCode plugin manifest
├── package.json                # Package metadata and scripts
├── tsconfig.json               # TypeScript configuration
└── README.md                   # This file

Architecture

OpenCode
    ↓ (events)
opencode-plugin.ts
    ↓ (raw events)
skill-event-normalizer.ts
    ↓ (normalized events)
getPrismaClient() (Prisma ORM)
    ↓ (stored in SQLite)
usage-stats.ts (queries)
    ↓ (aggregations)
User / Reports

Contributing

This is a private repository. To contribute:

1. Open an issue or discussion on GitHub
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes with tests
4. Open a Pull Request for review

License

MIT License — See LICENSE file for details.

Troubleshooting

Plugin not loading

1. Verify the path in your project's opencode.json points to node_modules/opencode-skill-tracker/dist/src/opencode-plugin.js
2. Ensure npm install was run and the package exists in node_modules
3. Check OpenCode's plugin loading logs for errors

Database is empty

1. Confirm the plugin is loaded (check OpenCode's plugin list)
2. The database is created on first event — interact with OpenCode to generate events
3. Check the database path exists and is writable

Data location

The database is created at a deterministic path:

• macOS/Linux: ~/.config/opencode-skill-tracker/skill-usage.db
• Windows: %LOCALAPPDATA%\opencode-skill-tracker\skill-usage.db

Override with the DATABASE_URL environment variable:

export DATABASE_URL="file:/custom/path.db"
npm install  # or npx opencode-skill-tracker db:init