cc-subagent 1.0.0

package/README.md

@@ -0,0 +1,59 @@
+# cc-subagent
+
+How many subagents does your Claude Code spawn? Shows subagent adoption rate, total count, peak sessions, and per-project breakdown.
+
+```
+cc-subagent — Claude Code subagent usage
+
+  Main sessions:         755
+  Sessions w/ subagents: 324 (42.9% of sessions)
+  Total subagent sessions: 3,677
+  Avg per spawning session: 11.3
+  Avg per all sessions:    4.9
+  Total subagent data:     1003.0 MB
+  Peak in one session:     284 subagents
+
+────────────────────────────────────────────────────────
+  Subagents per session (spawning sessions only)
+
+  1         ███████████░░░░░░░░░░░░░    64  (19.8%)
+  2-5       ████████████████████████   142  (43.8%)
+  6-10      ████████░░░░░░░░░░░░░░░░    48  (14.8%)
+  11-30     ███████░░░░░░░░░░░░░░░░░    43  (13.3%)
+  31-100    ████░░░░░░░░░░░░░░░░░░░░    21  (6.5%)
+  100+      █░░░░░░░░░░░░░░░░░░░░░░░     6  (1.9%)
+```
+
+## Usage
+
+```bash
+npx cc-subagent          # Subagent count and adoption stats
+npx cc-subagent --json   # JSON output
+```
+
+## What it shows
+
+- **Adoption rate** — what fraction of your sessions spawned at least one subagent
+- **Total count** — cumulative subagent sessions across your history
+- **Distribution** — single subagent vs teams of 100+
+- **Peak session** — the session that spawned the most subagents
+- **Subagent data size** — total disk usage of subagent session files
+- **By project** — which projects rely on subagents most
+
+## About subagents
+
+When Claude Code uses the `Agent` tool, it spawns a subagent — a child Claude session that handles a specific subtask. Subagent session files are stored at `~/.claude/projects/PROJ/SESSION_ID/subagents/agent-XXXXX.jsonl`.
+
+Most tools filter out subagent files by default. cc-subagent specifically analyzes what's usually hidden.
+
+## Privacy
+
+Reads file metadata only (names, sizes). No file content is accessed or transmitted. Everything runs locally.
+
+## Browser version
+
+Drop your `~/.claude` folder into [cc-subagent on the web](https://yurukusa.github.io/cc-subagent/) — no install required.
+
+---
+
+Part of [cc-toolkit](https://yurukusa.github.io/cc-toolkit/) — 60 free tools for Claude Code

package/cli.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * cc-subagent — How many subagents does your Claude Code spawn?
+ * Analyzes subagent usage: sessions, count, size, and per-project breakdown.
+ */
+
+import { readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const args = process.argv.slice(2);
+const jsonMode = args.includes('--json');
+const showHelp = args.includes('--help') || args.includes('-h');
+
+if (showHelp) {
+  console.log(`cc-subagent — Subagent usage in your Claude Code sessions
+
+Usage:
+  npx cc-subagent          # Subagent count, size, and project breakdown
+  npx cc-subagent --json   # JSON output
+`);
+  process.exit(0);
+}
+
+const claudeDir = join(homedir(), '.claude', 'projects');
+
+function humanSize(bytes) {
+  if (bytes >= 1024 ** 3) return (bytes / 1024 ** 3).toFixed(1) + ' GB';
+  if (bytes >= 1024 ** 2) return (bytes / 1024 ** 2).toFixed(1) + ' MB';
+  if (bytes >= 1024)      return (bytes / 1024).toFixed(1) + ' KB';
+  return bytes + ' B';
+}
+
+function projectName(dirName) {
+  const stripped = dirName.replace(/^-home-[^-]+/, '').replace(/^-/, '');
+  return stripped || '~/ (home)';
+}
+
+let projectDirs;
+try {
+  projectDirs = readdirSync(claudeDir);
+} catch {
+  console.error(`Cannot read ${claudeDir}`);
+  process.exit(1);
+}
+
+// Totals
+let totalMainSessions = 0;
+let sessionsWithSubagents = 0;
+let totalSubagentSessions = 0;
+let totalSubagentBytes = 0;
+let maxSubagentsInSession = 0;
+let maxSubagentsSession = '';
+
+const byProject = {};   // { projDir: { subagentSessions, parentSessions, bytes, name } }
+const distribution = { 1: 0, '2-5': 0, '6-10': 0, '11-30': 0, '31-100': 0, '100+': 0 };
+
+for (const projDir of projectDirs) {
+  const projPath = join(claudeDir, projDir);
+  let pstat;
+  try {
+    pstat = statSync(projPath);
+    if (!pstat.isDirectory()) continue;
+  } catch { continue; }
+
+  const projLabel = projectName(projDir);
+  if (!byProject[projDir]) byProject[projDir] = { subagentSessions: 0, parentSessions: 0, bytes: 0, name: projLabel };
+
+  // Each entry in projPath could be a session file OR a session dir (when it has subagents)
+  let entries;
+  try { entries = readdirSync(projPath); } catch { continue; }
+
+  // Count main sessions (*.jsonl files directly in projPath)
+  const mainSessions = entries.filter(e => e.endsWith('.jsonl'));
+  totalMainSessions += mainSessions.length;
+  byProject[projDir].parentSessions += mainSessions.length;
+
+  // Check subdirectories for session dirs with subagents
+  for (const entry of entries) {
+    if (entry.endsWith('.jsonl')) continue;  // skip session files
+    const sessionDir = join(projPath, entry);
+    let sdstat;
+    try {
+      sdstat = statSync(sessionDir);
+      if (!sdstat.isDirectory()) continue;
+    } catch { continue; }
+
+    const subagentsDir = join(sessionDir, 'subagents');
+    let subEntries;
+    try {
+      subEntries = readdirSync(subagentsDir);
+    } catch { continue; }
+
+    const subFiles = subEntries.filter(e => e.endsWith('.jsonl'));
+    if (!subFiles.length) continue;
+
+    // This session has subagents
+    sessionsWithSubagents++;
+    const sessionSubCount = subFiles.length;
+    totalSubagentSessions += sessionSubCount;
+
+    // Distribution bucket
+    if (sessionSubCount === 1)       distribution[1]++;
+    else if (sessionSubCount <= 5)   distribution['2-5']++;
+    else if (sessionSubCount <= 10)  distribution['6-10']++;
+    else if (sessionSubCount <= 30)  distribution['11-30']++;
+    else if (sessionSubCount <= 100) distribution['31-100']++;
+    else                              distribution['100+']++;
+
+    // Max
+    if (sessionSubCount > maxSubagentsInSession) {
+      maxSubagentsInSession = sessionSubCount;
+      maxSubagentsSession = `${projLabel}/${entry.slice(0, 8)}...`;
+    }
+
+    // Size of subagent files
+    let sessionSubBytes = 0;
+    for (const sf of subFiles) {
+      try {
+        sessionSubBytes += statSync(join(subagentsDir, sf)).size;
+      } catch {}
+    }
+    totalSubagentBytes += sessionSubBytes;
+    byProject[projDir].subagentSessions += sessionSubCount;
+    byProject[projDir].bytes += sessionSubBytes;
+  }
+}
+
+if (totalMainSessions === 0) {
+  console.error('No session files found.');
+  process.exit(1);
+}
+
+const adoptionRate = (sessionsWithSubagents / totalMainSessions * 100).toFixed(1);
+const avgPerSpawner = sessionsWithSubagents > 0 ? (totalSubagentSessions / sessionsWithSubagents).toFixed(1) : '0';
+const avgPerAll = (totalSubagentSessions / totalMainSessions).toFixed(1);
+
+const sortedProjects = Object.entries(byProject)
+  .filter(([, d]) => d.subagentSessions > 0)
+  .sort((a, b) => b[1].subagentSessions - a[1].subagentSessions);
+
+if (jsonMode) {
+  console.log(JSON.stringify({
+    main_sessions: totalMainSessions,
+    sessions_with_subagents: sessionsWithSubagents,
+    adoption_rate_pct: parseFloat(adoptionRate),
+    total_subagent_sessions: totalSubagentSessions,
+    avg_per_spawning_session: parseFloat(avgPerSpawner),
+    avg_per_all_sessions: parseFloat(avgPerAll),
+    total_subagent_size: humanSize(totalSubagentBytes),
+    max_in_single_session: maxSubagentsInSession,
+    distribution,
+    by_project: sortedProjects.slice(0, 10).map(([, d]) => ({
+      project: d.name,
+      subagent_sessions: d.subagentSessions,
+      size: humanSize(d.bytes),
+    })),
+  }, null, 2));
+  process.exit(0);
+}
+
+// Terminal display
+const BAR_WIDTH = 24;
+
+function countBar(n, max) {
+  const filled = max > 0 ? Math.round((n / max) * BAR_WIDTH) : 0;
+  return '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled);
+}
+
+function rpad(str, len) {
+  return str + ' '.repeat(Math.max(0, len - str.length));
+}
+
+console.log('cc-subagent — Claude Code subagent usage\n');
+
+console.log(`  Main sessions:        ${totalMainSessions.toLocaleString()}`);
+console.log(`  Sessions w/ subagents:${sessionsWithSubagents.toLocaleString().padStart(5)} (${adoptionRate}% of sessions)`);
+console.log(`  Total subagent sessions: ${totalSubagentSessions.toLocaleString()}`);
+console.log(`  Avg per spawning session: ${avgPerSpawner}`);
+console.log(`  Avg per all sessions:    ${avgPerAll}`);
+console.log(`  Total subagent data:     ${humanSize(totalSubagentBytes)}`);
+console.log(`  Peak in one session:     ${maxSubagentsInSession} subagents`);
+
+// Distribution
+console.log('\n' + '─'.repeat(56));
+console.log('  Subagents per session (spawning sessions only)\n');
+const maxDist = Math.max(...Object.values(distribution));
+for (const [label, count] of Object.entries(distribution)) {
+  const pct = sessionsWithSubagents > 0 ? (count / sessionsWithSubagents * 100).toFixed(1) : '0.0';
+  console.log(`  ${label.padEnd(8)}  ${countBar(count, maxDist)}  ${String(count).padStart(4)}  (${pct}%)`);
+}
+
+// Project breakdown
+if (sortedProjects.length) {
+  console.log('\n' + '─'.repeat(56));
+  console.log('  By project (top 8)\n');
+  const maxProj = sortedProjects[0][1].subagentSessions;
+  const maxLabel = Math.max(...sortedProjects.slice(0, 8).map(([, d]) => d.name.length));
+  for (const [, data] of sortedProjects.slice(0, 8)) {
+    const label = rpad(data.name, maxLabel);
+    console.log(`  ${label}  ${countBar(data.subagentSessions, maxProj)}  ${String(data.subagentSessions).padStart(4)}  ${humanSize(data.bytes)}`);
+  }
+}

package/index.html

@@ -0,0 +1,249 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>cc-subagent — Claude Code subagent usage</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    background: #0d1117;
+    color: #c9d1d9;
+    font-family: 'SF Mono', 'Consolas', 'Cascadia Code', monospace;
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    padding: 40px 20px;
+  }
+  h1 { font-size: 1.5rem; color: #ff7b72; margin-bottom: 6px; }
+  .subtitle { color: #8b949e; font-size: 0.875rem; margin-bottom: 32px; }
+
+  .drop-zone {
+    border: 2px dashed #30363d;
+    border-radius: 12px;
+    padding: 48px 64px;
+    text-align: center;
+    cursor: pointer;
+    transition: all 0.2s;
+    max-width: 480px;
+    width: 100%;
+    margin-bottom: 32px;
+  }
+  .drop-zone:hover, .drop-zone.drag-over { border-color: #ff7b72; background: rgba(255,123,114,0.05); }
+  .drop-text { color: #8b949e; font-size: 0.875rem; line-height: 1.6; }
+  .drop-text strong { color: #c9d1d9; }
+  #file-input { display: none; }
+
+  .result { display: none; max-width: 620px; width: 100%; }
+  .result.visible { display: block; }
+  .card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 20px; margin-bottom: 16px; }
+  .card-title { color: #8b949e; font-size: 0.75rem; text-transform: uppercase; letter-spacing: 1px; margin-bottom: 16px; }
+
+  .stats-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 12px; }
+  @media (min-width: 500px) { .stats-grid { grid-template-columns: repeat(3, 1fr); } }
+  .stat-item { text-align: center; }
+  .stat-val { font-size: 1.2rem; color: #ff7b72; font-weight: 700; }
+  .stat-lbl { font-size: 0.68rem; color: #8b949e; margin-top: 2px; }
+
+  .adoption-badge {
+    text-align: center;
+    padding: 12px;
+    background: rgba(255,123,114,0.1);
+    border: 1px solid rgba(255,123,114,0.3);
+    border-radius: 6px;
+    margin-top: 16px;
+    font-size: 0.9rem;
+    color: #ff7b72;
+  }
+
+  .bar-chart { font-size: 0.78rem; }
+  .bar-row { display: flex; align-items: center; gap: 8px; margin-bottom: 6px; }
+  .bar-label { width: 64px; text-align: right; color: #8b949e; flex-shrink: 0; }
+  .bar-label-wide { width: 160px; text-align: right; color: #c9d1d9; flex-shrink: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .bar-track { flex: 1; height: 14px; background: #21262d; border-radius: 3px; overflow: hidden; }
+  .bar-fill { height: 100%; background: #ff7b72; border-radius: 3px; transition: width 0.5s ease; }
+  .bar-count { width: 64px; color: #8b949e; text-align: right; flex-shrink: 0; font-size: 0.72rem; }
+
+  .section-title { color: #8b949e; font-size: 0.72rem; text-transform: uppercase; letter-spacing: 1px; margin-bottom: 10px; margin-top: 16px; }
+  .section-title:first-child { margin-top: 0; }
+
+  .reset-btn { margin-top: 16px; background: none; border: 1px solid #30363d; color: #8b949e; padding: 8px 16px; border-radius: 6px; cursor: pointer; font-family: inherit; font-size: 0.8rem; display: block; width: 100%; transition: all 0.2s; }
+  .reset-btn:hover { border-color: #ff7b72; color: #ff7b72; }
+  .footer { color: #8b949e; font-size: 0.75rem; text-align: center; margin-top: 12px; }
+  .footer a { color: #ff7b72; text-decoration: none; }
+  .footer a:hover { text-decoration: underline; }
+</style>
+</head>
+<body>
+<h1>🤖 cc-subagent</h1>
+<p class="subtitle">How many subagents does your Claude Code spawn?</p>
+
+<div class="drop-zone" id="drop-zone">
+  <div style="font-size:2.5rem;margin-bottom:12px;">📁</div>
+  <div class="drop-text">
+    <strong>Drop your ~/.claude folder here</strong><br>
+    or click to select<br><br>
+    Reads file metadata only (no content).<br>
+    Nothing is uploaded.
+  </div>
+  <input type="file" id="file-input" webkitdirectory multiple accept=".jsonl">
+</div>
+
+<div class="result" id="result">
+  <div class="card">
+    <div class="card-title">Subagent Summary</div>
+    <div class="stats-grid">
+      <div class="stat-item"><div class="stat-val" id="stat-main">—</div><div class="stat-lbl">main sessions</div></div>
+      <div class="stat-item"><div class="stat-val" id="stat-spawners">—</div><div class="stat-lbl">spawned subagents</div></div>
+      <div class="stat-item"><div class="stat-val" id="stat-total">—</div><div class="stat-lbl">total subagents</div></div>
+      <div class="stat-item"><div class="stat-val" id="stat-avg">—</div><div class="stat-lbl">avg per spawner</div></div>
+      <div class="stat-item"><div class="stat-val" id="stat-size">—</div><div class="stat-lbl">subagent data</div></div>
+      <div class="stat-item"><div class="stat-val" id="stat-peak">—</div><div class="stat-lbl">peak (1 session)</div></div>
+    </div>
+    <div class="adoption-badge" id="adoption-badge">—</div>
+  </div>
+
+  <div class="card">
+    <div class="section-title">Subagents per session (spawning sessions)</div>
+    <div class="bar-chart" id="dist-chart"></div>
+    <div class="section-title">By project (top 8)</div>
+    <div class="bar-chart" id="proj-chart"></div>
+  </div>
+
+  <button class="reset-btn" id="reset-btn">← Analyze another folder</button>
+</div>
+
+<div class="footer">
+  <a href="https://github.com/yurukusa/cc-subagent" target="_blank">cc-subagent</a> ·
+  Part of <a href="https://yurukusa.github.io/cc-toolkit/" target="_blank">cc-toolkit</a> · 106 free tools for Claude Code
+</div>
+
+<script>
+const dropZone = document.getElementById('drop-zone');
+const fileInput = document.getElementById('file-input');
+const resultEl = document.getElementById('result');
+const resetBtn = document.getElementById('reset-btn');
+
+dropZone.addEventListener('click', () => fileInput.click());
+dropZone.addEventListener('dragover', e => { e.preventDefault(); dropZone.classList.add('drag-over'); });
+dropZone.addEventListener('dragleave', () => dropZone.classList.remove('drag-over'));
+dropZone.addEventListener('drop', e => { e.preventDefault(); dropZone.classList.remove('drag-over'); processFiles(e.dataTransfer.files); });
+fileInput.addEventListener('change', () => processFiles(fileInput.files));
+resetBtn.addEventListener('click', () => { resultEl.classList.remove('visible'); dropZone.style.display = ''; fileInput.value = ''; });
+
+function humanSize(bytes) {
+  if (bytes >= 1024**3) return (bytes/1024**3).toFixed(1) + ' GB';
+  if (bytes >= 1024**2) return (bytes/1024**2).toFixed(1) + ' MB';
+  if (bytes >= 1024)    return (bytes/1024).toFixed(1) + ' KB';
+  return bytes + ' B';
+}
+
+function projectName(webkitPath) {
+  const parts = webkitPath.split('/');
+  const projIdx = parts.indexOf('projects');
+  if (projIdx >= 0 && parts[projIdx + 1]) {
+    const dir = parts[projIdx + 1];
+    const stripped = dir.replace(/^-home-[^-]+/, '').replace(/^-/, '');
+    return stripped || '~/ (home)';
+  }
+  return 'unknown';
+}
+
+function processFiles(files) {
+  const allFiles = Array.from(files);
+
+  // Separate main sessions and subagent files
+  const mainFiles = allFiles.filter(f => {
+    const p = f.webkitRelativePath || f.name;
+    return p.endsWith('.jsonl') && !p.includes('/subagents/');
+  });
+  const subFiles = allFiles.filter(f => {
+    const p = f.webkitRelativePath || f.name;
+    return p.endsWith('.jsonl') && p.includes('/subagents/');
+  });
+
+  if (!mainFiles.length && !subFiles.length) { alert('No session files found.'); return; }
+  dropZone.style.display = 'none';
+
+  // Group subagent files by parent session path
+  const byParent = {};   // parentPath → count + bytes
+  let totalSubBytes = 0;
+  for (const f of subFiles) {
+    const p = f.webkitRelativePath || f.name;
+    const parentPath = p.split('/subagents/')[0];
+    if (!byParent[parentPath]) byParent[parentPath] = { count: 0, bytes: 0 };
+    byParent[parentPath].count++;
+    byParent[parentPath].bytes += f.size;
+    totalSubBytes += f.size;
+  }
+
+  const totalMain = mainFiles.length;
+  const spawnerCount = Object.keys(byParent).length;
+  const totalSubCount = subFiles.length;
+  const adoptionRate = totalMain > 0 ? (spawnerCount / totalMain * 100) : 0;
+  const avgPerSpawner = spawnerCount > 0 ? (totalSubCount / spawnerCount).toFixed(1) : '0';
+
+  let peakCount = 0;
+  for (const d of Object.values(byParent)) {
+    if (d.count > peakCount) peakCount = d.count;
+  }
+
+  // Distribution
+  const dist = { 1: 0, '2-5': 0, '6-10': 0, '11-30': 0, '31-100': 0, '100+': 0 };
+  for (const d of Object.values(byParent)) {
+    const n = d.count;
+    if (n === 1)       dist[1]++;
+    else if (n <= 5)   dist['2-5']++;
+    else if (n <= 10)  dist['6-10']++;
+    else if (n <= 30)  dist['11-30']++;
+    else if (n <= 100) dist['31-100']++;
+    else               dist['100+']++;
+  }
+
+  // By project (using subagent file paths)
+  const byProj = {};
+  for (const f of subFiles) {
+    const proj = projectName(f.webkitRelativePath || f.name);
+    if (!byProj[proj]) byProj[proj] = { count: 0, bytes: 0 };
+    byProj[proj].count++;
+    byProj[proj].bytes += f.size;
+  }
+
+  // Render
+  document.getElementById('stat-main').textContent = totalMain.toLocaleString();
+  document.getElementById('stat-spawners').textContent = spawnerCount.toLocaleString();
+  document.getElementById('stat-total').textContent = totalSubCount.toLocaleString();
+  document.getElementById('stat-avg').textContent = avgPerSpawner;
+  document.getElementById('stat-size').textContent = humanSize(totalSubBytes);
+  document.getElementById('stat-peak').textContent = peakCount;
+  document.getElementById('adoption-badge').textContent =
+    `${adoptionRate.toFixed(1)}% of sessions spawned subagents · ${(totalSubCount / (totalMain || 1)).toFixed(1)} subagents per session on average`;
+
+  // Distribution chart
+  const maxDist = Math.max(...Object.values(dist), 1);
+  document.getElementById('dist-chart').innerHTML = Object.entries(dist).map(([label, count]) => {
+    const pct = spawnerCount > 0 ? (count / spawnerCount * 100).toFixed(1) : '0.0';
+    return `<div class="bar-row">
+      <div class="bar-label">${label}</div>
+      <div class="bar-track"><div class="bar-fill" style="width:${(count/maxDist*100).toFixed(1)}%"></div></div>
+      <div class="bar-count">${count} (${pct}%)</div>
+    </div>`;
+  }).join('');
+
+  // Project chart
+  const projs = Object.entries(byProj).sort((a,b) => b[1].count - a[1].count).slice(0, 8);
+  const maxProj = projs[0]?.[1].count || 1;
+  document.getElementById('proj-chart').innerHTML = projs.map(([name, d]) =>
+    `<div class="bar-row">
+      <div class="bar-label-wide">${name}</div>
+      <div class="bar-track"><div class="bar-fill" style="width:${(d.count/maxProj*100).toFixed(1)}%"></div></div>
+      <div class="bar-count">${d.count} / ${humanSize(d.bytes)}</div>
+    </div>`
+  ).join('');
+
+  resultEl.classList.add('visible');
+}
+</script>
+</body>
+</html>

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "cc-subagent",
+  "version": "1.0.0",
+  "description": "How many subagents does your Claude Code spawn? Session count, adoption rate, and per-project breakdown.",
+  "type": "module",
+  "bin": {
+    "cc-subagent": "./cli.mjs"
+  },
+  "scripts": {
+    "start": "node cli.mjs"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "developer-tools",
+    "analytics",
+    "agents"
+  ],
+  "author": "yurukusa",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}