skillio 0.1.2 → 0.1.4

package/README.md

@@ -9,29 +9,93 @@ Audit and manage AI agent skills for Claude Code and OpenAI Codex.
 
 ```sh
 # one-off (no install needed)
-npx skillio audit --agent claude --period 7d
-pnpm dlx skillio audit --agent codex --period 2w
+npx skillio --agent claude --period 7d
+pnpm dlx skillio --agent codex --period 2w
 
-# global install
-npm install -g skillio
+# global install — provides both `skillio` and `skl` commands in $PATH
+npm install -g skillio       # recommended
 pnpm add -g skillio
 ```
 
+### Local install (per-project)
+
+If you'd rather pin `skillio` to a single project (e.g. for CI) instead of
+installing globally:
+
+```sh
+npm install -D skillio       # adds to devDependencies
+pnpm add -D skillio
+yarn add -D skillio
+bun add -d skillio
+```
+
+Then run via your package manager — both `skillio` and `skl` are exposed:
+
+```sh
+npx skillio                  # works from any subdir of the project
+pnpm exec skl                # short alias
+yarn skl
+bun x skillio
+```
+
+You can also wire it into `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "audit:skills": "skl"
+  }
+}
+```
+
+…then `npm run audit:skills`.
+
+## Updating
+
+> Already have `skillio` installed? Get the latest version:
+
+```sh
+npm install -g skillio@latest        # recommended
+pnpm add -g skillio@latest
+```
+
+If you're on `0.1.3` or older — please upgrade. Newer versions add per-repo
+scoping, the `skl` short alias, and saner defaults (`skillio` with no flags now
+audits both Claude Code and Codex over all time).
+
 ## Usage
 
 ```sh
-skillio --agent claude --period 7d         # audit last 7 days (default subcommand)
-skillio audit --agent claude --period 7d   # audit last 7 days (attributed mode)
-skillio audit --agent codex --mode activations  # codex activations
-skillio audit -a claude codex --period 2w  # both agents, space-separated
-skillio audit -a claude,codex --period 2w  # both agents, comma-separated
-skillio list                                # list skills in local skills-lock.json
-skillio list --global                       # list from ~/.agents/.skill-lock.json
-skillio remove brainstorming               # remove skill from lock
+# from any repo: scoped to that repo
+skl                                    # both agents, all-time, this repo only
+skl -a claude --period 7d              # claude only, last 7 days, this repo
+
+# from $HOME (or anywhere with -g): global, all repos on this machine
+cd ~ && skl                            # auto-global when cwd === $HOME
+skl -g                                 # force global from any repo
+skl --global --period 1m               # global, last 30 days
+
+skillio …                              # same binary, longer alias
+skillio -a claude-code codex           # both agents (space-separated)
+skillio -a claude -a codex             # equivalent: repeated --agent flag
+skillio list                           # list skills in local skills-lock.json
+skillio list --global                  # list from ~/.agents/.skill-lock.json
+skillio remove brainstorming           # remove skill from lock
 skillio remove brainstorming writing-plans  # remove multiple skills
-skillio remove --dry-run brainstorming     # preview removal
+skillio remove --dry-run brainstorming # preview removal
 ```
 
+### Scope (per-repo vs global)
+
+`skillio` / `skl` automatically picks a scope based on your current directory:
+
+| where you run it | scope |
+|------------------|-------|
+| inside a git repo | that repo only (data filtered to its path) |
+| in `$HOME` exactly | global — all repos on this machine |
+| anywhere with `-g` / `--global` | global override |
+| with `--root <dir>` | that exact dir, treated as global |
+
 ## What it does
 
 - **Audit skill usage** — parse agent session logs and count which skills were invoked, when, and how often
@@ -39,23 +103,25 @@ skillio remove --dry-run brainstorming     # preview removal
 
 ## Options
 
-### `skillio` / `skillio audit`
+### `skillio` (audit)
 
-Audits skill usage from agent session logs. `audit` is the default subcommand when the first argument is an audit flag.
+Audits skill usage from agent session logs. This is the default operation —
+no subcommand keyword is needed.
 
 ```sh
 skillio --agent claude --period 7d
-skillio audit --agent codex --mode activations
+skillio --agent codex --mode activations
 ```
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `-a, --agent` | required | `claude-code`/`claude`, `codex`, comma- or space-separated |
-| `-p, --period` | `7d` | `7d`, `2w`, `1m`, `1y` |
+| `-a, --agent` | both | `claude-code`/`claude`, `codex` — pass both space-separated (`-a claude-code codex`) or repeat the flag (`-a claude -a codex`) |
+| `-p, --period` | `all` | `7d`, `2w`, `1m`, `1y`, `all` |
 | `--since` | — | `yyyy-mm-dd`, overrides `--period` |
-| `--mode` | `attributed` | `attributed` \| `activations` \| `mentions` |
+| `--mode` | `attributed` (claude) / `activations` (codex) | `attributed` \| `activations` \| `mentions` |
 | `--format` | `text` | `text` \| `json` |
-| `--root` | — | Override agent sessions directory |
+| `-g, --global` | `false` | Force global scope (ignore current directory) |
+| `--root` | — | Override agent sessions directory; implies global |
 | `--scan-all-files` | — | Ignore file mtime, read everything |
 
 ### Modes

package/dist/cli.js

@@ -545,6 +545,10 @@ function _getBuiltinFlags(long, short, userNames, userAliases) {
   return [`--${long}`, `-${short}`];
 }
 
+// src/commands/audit.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { join as join4 } from "node:path";
+
 // src/readers/claude.ts
 import { readFileSync as readFileSync2 } from "node:fs";
 
@@ -729,7 +733,64 @@ function readClaudeUsage(options) {
 }
 
 // src/readers/codex.ts
-import { existsSync, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
+
+// src/utils/scope.ts
+import { existsSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname, join as join3 } from "node:path";
+function detectScope(opts) {
+  const home = opts.home ?? homedir2();
+  if (opts.global || opts.rootOverride)
+    return { global: true };
+  if (norm(opts.cwd) === norm(home))
+    return { global: true };
+  return { global: false, projectRoot: findGitRoot(opts.cwd) ?? opts.cwd };
+}
+function isPathInProject(path, projectRoot) {
+  const p = norm(path);
+  const r = norm(projectRoot);
+  return p === r || p.startsWith(`${r}/`);
+}
+function encodeClaudeProjectDir(absPath) {
+  return absPath.replaceAll("/", "-");
+}
+function findGitRoot(start) {
+  let dir = start;
+  while (true) {
+    if (existsSync(join3(dir, ".git")))
+      return dir;
+    const parent = dirname(dir);
+    if (parent === dir)
+      return;
+    dir = parent;
+  }
+}
+function norm(p) {
+  return p.toLowerCase().replace(/\/+$/, "");
+}
+
+// src/readers/codex.ts
+function readSessionCwd(file) {
+  let head;
+  try {
+    head = readFileSync3(file, "utf8");
+  } catch {
+    return;
+  }
+  const lines = head.split(`
+`, 30);
+  for (const line of lines) {
+    if (!line.trim())
+      continue;
+    try {
+      const e = JSON.parse(line);
+      if (e.type === "session_meta" && typeof e.payload?.cwd === "string")
+        return e.payload.cwd;
+    } catch {}
+  }
+  return;
+}
 function readCodexUsage(options) {
   return options.mode === "mentions" ? readCodexMentions(options) : readCodexActivations(options);
 }
@@ -740,6 +801,11 @@ function readCodexActivations(options) {
   let linesRead = 0;
   const since = options.scanAllFiles ? undefined : options.since;
   for (const file of findJsonlFiles(root, since)) {
+    if (options.projectRoot) {
+      const sessionCwd = readSessionCwd(file);
+      if (!sessionCwd || !isPathInProject(sessionCwd, options.projectRoot))
+        continue;
+    }
     filesRead++;
     for (const line of readFileSync3(file, "utf8").split(`
 `)) {
@@ -765,7 +831,7 @@ function readCodexMentions(options) {
   const historyPath = expandHome(options.history ?? "~/.codex/history.jsonl");
   const counts = new Map;
   let linesRead = 0;
-  if (!existsSync(historyPath))
+  if (!existsSync2(historyPath))
     return { counts, filesRead: 0, linesRead: 0 };
   for (const line of readFileSync3(historyPath, "utf8").split(`
 `)) {
@@ -791,9 +857,11 @@ function readCodexMentions(options) {
 var UNITS = { d: 1, w: 7, m: 30, y: 365 };
 var MS_PER_DAY = 24 * 60 * 60 * 1000;
 function parsePeriod(period) {
+  if (period === "all")
+    return Number.POSITIVE_INFINITY;
   const match = period.match(/^(\d+)([dwmy])$/);
   if (!match)
-    throw new Error(`Invalid period: "${period}". Use values like 7d, 2w, 1m, 1y.`);
+    throw new Error(`Invalid period: "${period}". Use values like 7d, 2w, 1m, 1y, all.`);
   const unit = UNITS[match[2] ?? ""] ?? 1;
   return Number(match[1]) * unit;
 }
@@ -801,13 +869,13 @@ function parsePeriod(period) {
 // src/commands/audit.ts
 function parseAgents(agent) {
   if (!agent)
-    throw new Error("--agent is required. Use --agent claude-code, --agent codex, or both.");
-  const normalized = agent.split(",").map((a) => a.trim()).map((a) => {
+    return ["claude-code", "codex"];
+  const normalized = agent.split("\x1F").map((a) => a.trim()).filter(Boolean).map((a) => {
     if (a === "codex")
       return "codex";
     if (["claude", "claude-code", "claudecode"].includes(a))
       return "claude-code";
-    throw new Error(`Unknown agent: "${a}". Use "claude-code" or "codex".`);
+    throw new Error(`Unknown agent: "${a}". Use "claude-code" or "codex" (space-separated for both: -a claude-code codex).`);
   });
   return [...new Set(normalized)];
 }
@@ -816,21 +884,26 @@ function toRows(counts) {
 }
 async function runAudit(args) {
   const agents = parseAgents(args.agent);
-  const since = args.since ? new Date(`${args.since}T00:00:00`) : new Date(Date.now() - parsePeriod(args.period) * 24 * 60 * 60 * 1000);
+  const allTime = !args.since && args.period === "all";
+  const since = args.since ? new Date(`${args.since}T00:00:00`) : args.period === "all" ? new Date(0) : new Date(Date.now() - parsePeriod(args.period) * 24 * 60 * 60 * 1000);
+  const scanAllFiles = allTime || args["scan-all-files"];
   if (Number.isNaN(since.getTime())) {
     console.error(`Invalid --since value: ${args.since}`);
     process.exit(1);
   }
+  const scope = detectScope({
+    global: args.global,
+    rootOverride: !!args.root,
+    cwd: process.cwd()
+  });
+  const claudeProjectsRoot = expandHome("~/.claude/projects");
+  const claudeRoot = args.root ?? (scope.projectRoot ? join4(claudeProjectsRoot, encodeClaudeProjectDir(scope.projectRoot)) : claudeProjectsRoot);
+  const claudeRootMissing = !args.root && !!scope.projectRoot && !existsSync3(claudeRoot);
   const results = [];
   for (const agent of agents) {
     if (agent === "claude-code") {
       const mode = args.mode ?? "attributed";
-      const result = readClaudeUsage({
-        since,
-        mode,
-        root: args.root,
-        scanAllFiles: args["scan-all-files"]
-      });
+      const result = claudeRootMissing ? { counts: new Map, filesRead: 0, linesRead: 0 } : readClaudeUsage({ since, mode, root: claudeRoot, scanAllFiles });
       results.push({
         agent,
         mode,
@@ -843,7 +916,8 @@ async function runAudit(args) {
         since,
         mode,
         root: args.root,
-        scanAllFiles: args["scan-all-files"]
+        scanAllFiles,
+        projectRoot: scope.projectRoot
       });
       results.push({
         agent,
@@ -863,9 +937,12 @@ async function runAudit(args) {
     console.log(JSON.stringify(output.length === 1 ? output[0] : output, null, 2));
     return;
   }
+  const sinceLabel = allTime ? "all-time" : `since ${since.toISOString().slice(0, 10)}`;
+  const scopeLabel = scope.global ? "global" : scope.projectRoot ?? "global";
+  console.log(`Scope: ${scopeLabel}${scope.global ? "" : "  (use -g for global)"}`);
   for (const { agent, mode, rows, stats } of results) {
     console.log(`
-${agent} skill usage since ${since.toISOString().slice(0, 10)} (${mode})`);
+${agent} skill usage ${sinceLabel} (${mode})`);
     console.log(`Files read: ${stats.filesRead}; JSONL lines read: ${stats.linesRead}`);
     if (rows.length === 0) {
       console.log("No skills found.");
@@ -876,64 +953,63 @@ ${agent} skill usage since ${since.toISOString().slice(0, 10)} (${mode})`);
     }
   }
 }
-var auditCommand = defineCommand({
-  meta: { description: "Audit skill usage from agent session logs" },
-  args: {
-    agent: { type: "string", alias: "a", description: "claude-code, codex, or comma-separated" },
-    period: { type: "string", alias: "p", default: "7d", description: "7d, 2w, 1m, 1y" },
-    since: { type: "string", description: "yyyy-mm-dd, overrides --period" },
-    mode: { type: "string", description: "attributed | activations | mentions" },
-    format: { type: "string", default: "text", description: "text | json" },
-    root: { type: "string", description: "Override agent sessions directory" },
-    "scan-all-files": { type: "boolean", default: false, description: "Ignore file mtime" }
+var auditArgs = {
+  agent: {
+    type: "string",
+    alias: "a",
+    description: "claude-code, codex (default: both; pass space-separated for both)"
   },
-  async run({ args }) {
-    try {
-      await runAudit(args);
-    } catch (e) {
-      console.error(e instanceof Error ? e.message : String(e));
-      process.exit(1);
-    }
+  period: { type: "string", alias: "p", default: "all", description: "7d, 2w, 1m, 1y, all" },
+  since: { type: "string", description: "yyyy-mm-dd, overrides --period" },
+  mode: { type: "string", description: "attributed | activations | mentions" },
+  format: { type: "string", default: "text", description: "text | json" },
+  root: { type: "string", description: "Override agent sessions directory; implies global" },
+  "scan-all-files": { type: "boolean", default: false, description: "Ignore file mtime" },
+  global: {
+    type: "boolean",
+    alias: "g",
+    default: false,
+    description: "Force global scope (ignore current directory)"
   }
-});
+};
 
 // src/lock/file.ts
 import {
   copyFileSync,
-  existsSync as existsSync2,
+  existsSync as existsSync4,
   mkdirSync,
   readFileSync as readFileSync4,
   renameSync,
   writeFileSync
 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { basename, dirname, join as join3 } from "node:path";
+import { homedir as homedir3 } from "node:os";
+import { basename, dirname as dirname2, join as join5 } from "node:path";
 function getLockPath(global) {
-  return global ? join3(homedir2(), ".agents", ".skill-lock.json") : "skills-lock.json";
+  return global ? join5(homedir3(), ".agents", ".skill-lock.json") : "skills-lock.json";
 }
 function readLock(path) {
-  if (!existsSync2(path))
+  if (!existsSync4(path))
     return { skills: {} };
   return JSON.parse(readFileSync4(path, "utf8"));
 }
 function writeLock(path, lock) {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = join3(dirname(path), `.${Date.now()}.skill-lock.json`);
+  mkdirSync(dirname2(path), { recursive: true });
+  const tmp = join5(dirname2(path), `.${Date.now()}.skill-lock.json`);
   writeFileSync(tmp, `${JSON.stringify(lock, null, 2)}
 `);
   renameSync(tmp, path);
 }
 function getBackupPath(path) {
-  return join3(dirname(path), ".tmp", `${basename(path)}.bak`);
+  return join5(dirname2(path), ".tmp", `${basename(path)}.bak`);
 }
 function backupLock(path) {
   const backupPath = getBackupPath(path);
-  mkdirSync(dirname(backupPath), { recursive: true });
+  mkdirSync(dirname2(backupPath), { recursive: true });
   copyFileSync(path, backupPath);
   return backupPath;
 }
 function removeSkillFromLock(path, skill, { skipBackup = false } = {}) {
-  if (!existsSync2(path))
+  if (!existsSync4(path))
     return { removed: false };
   const lock = readLock(path);
   if (!Object.hasOwn(lock.skills, skill))
@@ -959,7 +1035,7 @@ var listCommand = defineCommand({
 });
 
 // src/commands/remove.ts
-import { existsSync as existsSync3 } from "node:fs";
+import { existsSync as existsSync5 } from "node:fs";
 var removeCommand = defineCommand({
   meta: { description: "Remove one or more skills from the lock file" },
   args: {
@@ -981,7 +1057,7 @@ var removeCommand = defineCommand({
       }
       return;
     }
-    const backupPath = existsSync3(path) ? backupLock(path) : undefined;
+    const backupPath = existsSync5(path) ? backupLock(path) : undefined;
     for (const skill of skills) {
       const result = removeSkillFromLock(path, skill, { skipBackup: true });
       if (result.removed) {
@@ -999,20 +1075,61 @@ var removeCommand = defineCommand({
 
 // src/cli.ts
 var { version } = createRequire(import.meta.url)("../package.json");
-var SUBCOMMANDS = new Set(["audit", "list", "ls", "remove", "rm"]);
-var HELP_FLAGS = new Set(["--help", "-h", "--version", "-v"]);
-var firstArg = process.argv[2];
-if (firstArg === undefined || !SUBCOMMANDS.has(firstArg) && !HELP_FLAGS.has(firstArg)) {
-  process.argv.splice(2, 0, "audit");
+if (process.argv[2] === "audit") {
+  process.argv.splice(2, 1);
 }
+function mergeAgentArgs(argv) {
+  const out = [];
+  const values = [];
+  let slotIdx = -1;
+  let i = 0;
+  while (i < argv.length) {
+    const tok = argv[i];
+    if (tok === undefined) {
+      i++;
+      continue;
+    }
+    if (tok === "-a" || tok === "--agent") {
+      if (slotIdx === -1)
+        slotIdx = out.length;
+      let j = i + 1;
+      while (j < argv.length) {
+        const next = argv[j];
+        if (next === undefined || next.startsWith("-"))
+          break;
+        values.push(next);
+        j++;
+      }
+      i = j;
+      continue;
+    }
+    out.push(tok);
+    i++;
+  }
+  if (values.length > 0 && slotIdx !== -1)
+    out.splice(slotIdx, 0, "--agent", values.join("\x1F"));
+  return out;
+}
+process.argv = mergeAgentArgs(process.argv);
+var SUBCOMMAND_NAMES = new Set(["list", "ls", "remove", "rm"]);
 var main = defineCommand({
   meta: {
     name: "skillio",
     version,
     description: "Audit and manage AI agent skills"
   },
+  args: auditArgs,
+  async run({ args }) {
+    if (SUBCOMMAND_NAMES.has(process.argv[2] ?? ""))
+      return;
+    try {
+      await runAudit(args);
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
+  },
   subCommands: {
-    audit: auditCommand,
     list: listCommand,
     ls: listCommand,
     remove: removeCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillio",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Audit and manage AI agent skills for Claude Code and Codex",
   "license": "MIT",
   "author": "ihororlovskyi",