@viren/claude-code-dashboard 0.0.1

package/src/analysis.mjs

@@ -0,0 +1,262 @@
+import { readdirSync, readFileSync } from "fs";
+import { join } from "path";
+import { STACK_FILES } from "./constants.mjs";
+import { gitCmd } from "./helpers.mjs";
+
+export function computeHealthScore(repo) {
+  let score = 0;
+  const reasons = [];
+
+  // Has AGENTS.md/CLAUDE.md (30 points)
+  if (repo.hasAgentsFile) {
+    score += 30;
+  } else {
+    reasons.push("add CLAUDE.md");
+  }
+
+  // Has description (10 points)
+  if (repo.desc && repo.desc.length > 0) {
+    score += 10;
+  } else {
+    reasons.push("add project description");
+  }
+
+  // Has commands (20 points)
+  if (repo.commandCount > 0) {
+    score += Math.min(20, repo.commandCount * 10);
+  } else {
+    reasons.push("add commands");
+  }
+
+  // Has rules (20 points)
+  if (repo.ruleCount > 0) {
+    score += Math.min(20, repo.ruleCount * 10);
+  } else {
+    reasons.push("add rules");
+  }
+
+  // Has sections / structured config (10 points)
+  if (repo.sectionCount > 0) {
+    score += Math.min(10, repo.sectionCount * 2);
+  } else {
+    reasons.push("add structured sections");
+  }
+
+  // Freshness (10 points)
+  if (repo.freshnessClass === "fresh") {
+    score += 10;
+  } else if (repo.freshnessClass === "aging") {
+    score += 5;
+    reasons.push("update config (aging)");
+  } else {
+    reasons.push("update config (stale)");
+  }
+
+  return { score: Math.min(100, score), reasons };
+}
+
+export function detectTechStack(repoDir) {
+  const stacks = new Set();
+
+  try {
+    const entries = new Set(readdirSync(repoDir));
+
+    for (const [file, stack] of Object.entries(STACK_FILES)) {
+      if (entries.has(file)) stacks.add(stack);
+    }
+
+    if (entries.has("package.json")) {
+      // Check for React/Expo in package.json if no framework detected yet
+      if (!stacks.has("next") && !stacks.has("expo")) {
+        try {
+          const pkg = JSON.parse(readFileSync(join(repoDir, "package.json"), "utf8"));
+          const allDeps = {
+            ...(pkg.dependencies || {}),
+            ...(pkg.devDependencies || {}),
+          };
+          if (allDeps["expo"]) stacks.add("expo");
+          else if (allDeps["next"]) stacks.add("next");
+          else if (allDeps["react"]) stacks.add("react");
+        } catch {
+          /* malformed package.json */
+        }
+      }
+      if (stacks.size === 0) stacks.add("node");
+    }
+  } catch {
+    /* unreadable dir */
+  }
+
+  return { stacks: [...stacks] };
+}
+
+export function computeDrift(repoDir, configTimestamp) {
+  if (!configTimestamp) return { level: "unknown", commitsSince: 0 };
+
+  // Count commits since the config was last updated
+  const countStr = gitCmd(repoDir, "rev-list", "--count", `--since=${configTimestamp}`, "HEAD");
+  if (!countStr) return { level: "unknown", commitsSince: 0 };
+
+  const parsed = Number(countStr);
+  if (!Number.isFinite(parsed)) return { level: "unknown", commitsSince: 0 };
+
+  const commitsSince = Math.max(0, parsed - 1); // -1 to exclude the config commit itself
+
+  if (commitsSince === 0) return { level: "synced", commitsSince: 0 };
+  if (commitsSince <= 5) return { level: "low", commitsSince };
+  if (commitsSince <= 20) return { level: "medium", commitsSince };
+  return { level: "high", commitsSince };
+}
+
+export function findExemplar(stack, configuredRepos) {
+  if (!stack || stack.length === 0) return null;
+  let best = null;
+  let bestScore = -1;
+  for (const repo of configuredRepos) {
+    const repoStacks = repo.techStack || [];
+    const overlap = stack.filter((s) => repoStacks.includes(s)).length;
+    const score = overlap * 100 + (repo.healthScore || 0);
+    if (overlap > 0 && score > bestScore) {
+      bestScore = score;
+      best = repo;
+    }
+  }
+  return best;
+}
+
+export function generateSuggestions(exemplar) {
+  if (!exemplar) return [];
+  const suggestions = [];
+  if (exemplar.hasAgentsFile) suggestions.push("add CLAUDE.md");
+  if (exemplar.commands?.length > 0)
+    suggestions.push(`add commands (${exemplar.name} has ${exemplar.commands.length})`);
+  if (exemplar.rules?.length > 0)
+    suggestions.push(`add rules (${exemplar.name} has ${exemplar.rules.length})`);
+  return suggestions;
+}
+
+export function detectConfigPattern(repo) {
+  if (repo.rules.length >= 3) return "modular";
+  if (repo.sections.length >= 3) return "monolithic";
+  if (repo.commands.length >= 2 && repo.sections.length === 0) return "command-heavy";
+  return "minimal";
+}
+
+export function computeConfigSimilarity(repoA, repoB) {
+  if (!repoA || !repoB) return 0;
+  let matches = 0;
+  let total = 0;
+
+  // Section name overlap (Jaccard similarity)
+  const sectionsA = new Set((repoA.sections || []).map((s) => s.name || s));
+  const sectionsB = new Set((repoB.sections || []).map((s) => s.name || s));
+  if (sectionsA.size > 0 || sectionsB.size > 0) {
+    const intersection = [...sectionsA].filter((s) => sectionsB.has(s)).length;
+    const union = new Set([...sectionsA, ...sectionsB]).size;
+    matches += intersection;
+    total += union;
+  }
+
+  // Stack overlap
+  const stackA = new Set(repoA.techStack || []);
+  const stackB = new Set(repoB.techStack || []);
+  if (stackA.size > 0 || stackB.size > 0) {
+    const intersection = [...stackA].filter((s) => stackB.has(s)).length;
+    const union = new Set([...stackA, ...stackB]).size;
+    matches += intersection;
+    total += union;
+  }
+
+  // Same config pattern bonus
+  if (repoA.configPattern && repoA.configPattern === repoB.configPattern) {
+    matches += 1;
+    total += 1;
+  } else {
+    total += 1;
+  }
+
+  return total > 0 ? Math.round((matches / total) * 100) : 0;
+}
+
+export function matchSkillsToRepo(repo, skills) {
+  if (!repo || !skills || skills.length === 0) return [];
+  const repoTokens = new Set();
+  for (const word of repo.name.toLowerCase().split(/[-_./]/)) {
+    if (word.length > 1) repoTokens.add(word);
+  }
+  for (const s of repo.techStack || []) {
+    repoTokens.add(s.toLowerCase());
+  }
+  for (const sec of repo.sections || []) {
+    const name = (sec.name || sec || "").toLowerCase();
+    for (const word of name.split(/\s+/)) {
+      if (word.length > 2) repoTokens.add(word);
+    }
+  }
+  const matched = [];
+  for (const skill of skills) {
+    const skillTokens = skill.name
+      .toLowerCase()
+      .split(/[-_./]/)
+      .filter((t) => t.length > 1);
+    const hits = skillTokens.filter((t) => repoTokens.has(t)).length;
+    if (hits > 0) matched.push({ name: skill.name, relevance: hits });
+  }
+  return matched.sort((a, b) => b.relevance - a.relevance).slice(0, 5);
+}
+
+export function lintConfig(repo) {
+  const issues = [];
+  if (repo.sections) {
+    for (const sec of repo.sections) {
+      const name = sec.name || sec || "";
+      if (/TODO|FIXME|HACK/i.test(name)) {
+        issues.push({ level: "warn", message: `Section "${name}" contains TODO/FIXME marker` });
+      }
+    }
+  }
+  if (!repo.hasAgentsFile && (repo.commands.length > 0 || repo.rules.length > 0)) {
+    issues.push({ level: "info", message: "Has commands/rules but no CLAUDE.md" });
+  }
+  if (
+    repo.hasAgentsFile &&
+    repo.commands.length === 0 &&
+    repo.rules.length === 0 &&
+    (repo.sections || []).length === 0
+  ) {
+    issues.push({
+      level: "warn",
+      message: "CLAUDE.md exists but has no commands, rules, or sections",
+    });
+  }
+  return issues;
+}
+
+export function computeDashboardDiff(prev, current) {
+  const diff = { added: [], removed: [], changed: [] };
+  if (!prev || !current) return diff;
+  const prevNames = new Set((prev.configuredRepos || []).map((r) => r.name));
+  const currNames = new Set((current.configuredRepos || []).map((r) => r.name));
+  for (const name of currNames) {
+    if (!prevNames.has(name)) diff.added.push(name);
+  }
+  for (const name of prevNames) {
+    if (!currNames.has(name)) diff.removed.push(name);
+  }
+  const prevMap = Object.fromEntries((prev.configuredRepos || []).map((r) => [r.name, r]));
+  const currMap = Object.fromEntries((current.configuredRepos || []).map((r) => [r.name, r]));
+  for (const name of currNames) {
+    if (
+      prevNames.has(name) &&
+      (prevMap[name].healthScore || 0) !== (currMap[name].healthScore || 0)
+    ) {
+      diff.changed.push({
+        name,
+        field: "healthScore",
+        from: prevMap[name].healthScore || 0,
+        to: currMap[name].healthScore || 0,
+      });
+    }
+  }
+  return diff;
+}

package/src/cli.mjs

@@ -0,0 +1,135 @@
+import { VERSION, DEFAULT_OUTPUT, HOME } from "./constants.mjs";
+
+export function parseArgs(argv) {
+  const args = {
+    output: DEFAULT_OUTPUT,
+    open: false,
+    json: false,
+    catalog: false,
+    command: null,
+    template: null,
+    dryRun: false,
+    quiet: false,
+    watch: false,
+    diff: false,
+    anonymize: false,
+    completions: false,
+  };
+  let i = 2; // skip node + script
+  if (argv[2] === "init") {
+    args.command = "init";
+    i = 3;
+  } else if (argv[2] === "lint") {
+    args.command = "lint";
+    i = 3;
+  }
+  while (i < argv.length) {
+    switch (argv[i]) {
+      case "--help":
+      case "-h":
+        console.log(`claude-code-dashboard v${VERSION}
+
+Scans your home directory for git repos with Claude Code configuration
+and generates a self-contained HTML dashboard.
+
+Usage:
+  claude-code-dashboard [options]
+
+Options:
+  --output, -o <path>  Output path (default: ~/.claude/dashboard.html)
+  --json               Output full data model as JSON instead of HTML
+  --catalog            Generate a shareable skill catalog HTML page
+  --open               Open the dashboard in your default browser after generating
+  --quiet              Suppress output, just write file
+  --watch              Regenerate on file changes
+  --diff               Show changes since last generation
+  --anonymize          Anonymize paths for shareable export
+  --completions        Output shell completion script for bash/zsh
+  --version, -v        Show version
+  --help, -h           Show this help
+
+Subcommands:
+  init                 Scaffold Claude Code config for current directory
+    --template, -t <stack>  Override auto-detected stack (next, react, python, etc.)
+    --dry-run               Preview what would be created without writing files
+  lint                 Check all repos for config issues
+
+Config file: ~/.claude/dashboard.conf
+  Add directories (one per line) to restrict scanning scope.
+  Define dependency chains: chain: A -> B -> C
+  Lines starting with # are comments.`);
+        process.exit(0);
+      case "--version":
+      case "-v":
+        console.log(VERSION);
+        process.exit(0);
+      case "--output":
+      case "-o":
+        args.output = argv[++i];
+        if (!args.output) {
+          console.error("Error: --output requires a path argument");
+          process.exit(1);
+        }
+        // Expand ~ at the start of the path
+        if (args.output.startsWith("~")) {
+          args.output = args.output.replace(/^~/, HOME);
+        }
+        break;
+      case "--json":
+        args.json = true;
+        break;
+      case "--catalog":
+        args.catalog = true;
+        break;
+      case "--open":
+        args.open = true;
+        break;
+      case "--template":
+      case "-t":
+        args.template = argv[++i];
+        if (!args.template) {
+          console.error("Error: --template requires a stack argument");
+          process.exit(1);
+        }
+        break;
+      case "--dry-run":
+        args.dryRun = true;
+        break;
+      case "--quiet":
+        args.quiet = true;
+        break;
+      case "--watch":
+        args.watch = true;
+        break;
+      case "--diff":
+        args.diff = true;
+        break;
+      case "--anonymize":
+        args.anonymize = true;
+        break;
+      case "--completions":
+        args.completions = true;
+        break;
+      default:
+        console.error(`Unknown option: ${argv[i]}\nRun with --help for usage.`);
+        process.exit(1);
+    }
+    i++;
+  }
+  return args;
+}
+
+export function generateCompletions() {
+  console.log(`# claude-code-dashboard completions
+# eval "$(claude-code-dashboard --completions)"
+if [ -n "$ZSH_VERSION" ]; then
+  _claude_code_dashboard() {
+    local -a opts; opts=(init lint --output --open --json --catalog --quiet --watch --diff --anonymize --completions --help --version)
+    if (( CURRENT == 2 )); then _describe 'option' opts; fi
+  }; compdef _claude_code_dashboard claude-code-dashboard
+elif [ -n "$BASH_VERSION" ]; then
+  _claude_code_dashboard() { COMPREPLY=( $(compgen -W "init lint --output --open --json --catalog --quiet --watch --diff --anonymize --completions --help --version" -- "\${COMP_WORDS[COMP_CWORD]}") ); }
+  complete -F _claude_code_dashboard claude-code-dashboard
+fi`);
+  process.exit(0);
+}

package/src/constants.mjs

@@ -0,0 +1,150 @@
+import { join } from "path";
+import { homedir } from "os";
+
+export const VERSION = "0.0.1";
+
+export const HOME = homedir();
+export const CLAUDE_DIR = join(HOME, ".claude");
+export const DEFAULT_OUTPUT = join(CLAUDE_DIR, "dashboard.html");
+export const CONF = join(CLAUDE_DIR, "dashboard.conf");
+export const MAX_DEPTH = 5;
+
+// Freshness thresholds (seconds)
+export const ONE_DAY = 86_400;
+export const TWO_DAYS = 172_800;
+export const THIRTY_DAYS = 2_592_000;
+export const NINETY_DAYS = 7_776_000;
+export const ONE_YEAR = 31_536_000;
+
+// Directories to skip during repo discovery
+export const PRUNE = new Set([
+  "node_modules",
+  ".Trash",
+  "Library",
+  ".cache",
+  ".npm",
+  ".yarn",
+  ".pnpm",
+  ".local",
+  ".cargo",
+  ".rustup",
+  ".gradle",
+  ".m2",
+  ".cocoapods",
+  ".android",
+  "Caches",
+  ".virtualenvs",
+  ".pyenv",
+  ".nvm",
+  ".rbenv",
+  ".gem",
+  ".docker",
+  ".orbstack",
+  "go",
+  "venv",
+  "__pycache__",
+  ".tox",
+  ".git",
+]);
+
+// Lines matching these patterns are skipped when extracting project descriptions.
+// Override by adding a YAML frontmatter `description:` field to your CLAUDE.md.
+const BOILERPLATE_PATTERNS = [
+  "This file provides guidance",
+  "CLAUDE.md.*symlink",
+  "AGENTS.md.*should contain",
+  "Always-loaded guidance",
+  "Guidance for coding agents",
+  "Rules are split into focused files",
+  "Detailed implementation guidance lives in",
+];
+export const BOILERPLATE_RE = new RegExp(BOILERPLATE_PATTERNS.join("|"));
+
+export const STACK_FILES = {
+  "next.config.js": "next",
+  "next.config.mjs": "next",
+  "next.config.ts": "next",
+  "Cargo.toml": "rust",
+  "go.mod": "go",
+  "requirements.txt": "python",
+  "pyproject.toml": "python",
+  "setup.py": "python",
+  "Package.swift": "swift",
+  Gemfile: "ruby",
+  "pom.xml": "java",
+  "build.gradle": "java",
+  "build.gradle.kts": "java",
+};
+
+export const SKILL_CATEGORIES = {
+  workflow: ["plan", "workflow", "branch", "commit", "pr-", "review", "ship", "deploy", "execute"],
+  "code-quality": ["lint", "test-", "quality", "format", "refactor", "clean", "verify", "tdd"],
+  debugging: ["debug", "diagnose", "troubleshoot", "ci-fix", "stack-trace", "breakpoint"],
+  research: [
+    "research",
+    "search",
+    "analyze",
+    "explore",
+    "investigate",
+    "compare",
+    "competitive",
+    "audit",
+    "find",
+  ],
+  integrations: ["slack", "github", "figma", "linear", "jira", "notion", "snowflake", "api", "mcp"],
+  "project-specific": ["storybook", "react-native"],
+};
+
+export const CATEGORY_ORDER = [
+  "workflow",
+  "code-quality",
+  "debugging",
+  "research",
+  "integrations",
+  "project-specific",
+];
+
+// Last verified against Claude Code v2.1.72 (March 2026)
+export const QUICK_REFERENCE = {
+  essentialCommands: [
+    { cmd: "/help", desc: "Show help and available commands" },
+    { cmd: "/compact", desc: "Compact conversation to free context" },
+    { cmd: "/model", desc: "Switch AI model" },
+    { cmd: "/diff", desc: "Interactive diff viewer for changes" },
+    { cmd: "/status", desc: "Version, model, account info" },
+    { cmd: "/cost", desc: "Show token usage statistics" },
+    { cmd: "/plan", desc: "Enter plan mode for complex tasks" },
+    { cmd: "/config", desc: "Open settings interface" },
+    { cmd: "/mcp", desc: "Manage MCP server connections" },
+    { cmd: "/memory", desc: "Edit CLAUDE.md, toggle auto-memory" },
+    { cmd: "/permissions", desc: "View or update tool permissions" },
+    { cmd: "/init", desc: "Initialize project with CLAUDE.md" },
+    { cmd: "/insights", desc: "Generate usage analytics report" },
+    { cmd: "/export", desc: "Export conversation as plain text" },
+    { cmd: "/pr-comments", desc: "Fetch GitHub PR review comments" },
+    { cmd: "/doctor", desc: "Diagnose installation issues" },
+  ],
+  tools: [
+    { name: "Bash", desc: "Execute shell commands" },
+    { name: "Read", desc: "Read files (text, images, PDFs, notebooks)" },
+    { name: "Write", desc: "Create new files" },
+    { name: "Edit", desc: "Modify files via exact string replacement" },
+    { name: "Grep", desc: "Search file contents with regex" },
+    { name: "Glob", desc: "Find files by pattern" },
+    { name: "Agent", desc: "Launch specialized sub-agents" },
+    { name: "WebSearch", desc: "Search the web" },
+    { name: "WebFetch", desc: "Fetch URL content" },
+    { name: "LSP", desc: "Code intelligence (go-to-def, references)" },
+  ],
+  shortcuts: [
+    { keys: "/", desc: "Quick command search" },
+    { keys: "!", desc: "Bash mode (run directly)" },
+    { keys: "@", desc: "File path autocomplete" },
+    { keys: "Ctrl+C", desc: "Cancel generation" },
+    { keys: "Ctrl+L", desc: "Clear screen" },
+    { keys: "Ctrl+R", desc: "Search history" },
+    { keys: "Shift+Tab", desc: "Toggle permission mode" },
+    { keys: "Esc Esc", desc: "Rewind conversation" },
+    { keys: "Tab", desc: "Toggle thinking" },
+  ],
+};

package/src/discovery.mjs

@@ -0,0 +1,46 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { PRUNE, CONF, HOME } from "./constants.mjs";
+
+export function findGitRepos(roots, maxDepth) {
+  const repos = [];
+  function walk(dir, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry === ".git") {
+        repos.push(dir);
+        return; // don't recurse inside a git repo's subdirs
+      }
+      if (PRUNE.has(entry)) continue;
+      const full = join(dir, entry);
+      try {
+        if (statSync(full).isDirectory()) walk(full, depth + 1);
+      } catch {
+        /* permission denied, symlink loops, etc */
+      }
+    }
+  }
+  for (const root of roots) {
+    if (existsSync(root)) walk(root, 0);
+  }
+  return repos;
+}
+
+export function getScanRoots() {
+  if (existsSync(CONF)) {
+    const dirs = readFileSync(CONF, "utf8")
+      .split("\n")
+      .map((l) => l.replace(/#.*/, "").trim())
+      .filter((l) => l && !l.startsWith("chain:"))
+      .map((l) => l.replace(/^~/, HOME))
+      .filter((d) => existsSync(d));
+    if (dirs.length) return dirs;
+  }
+  return [HOME];
+}

package/src/freshness.mjs

@@ -0,0 +1,35 @@
+import { ONE_DAY, TWO_DAYS, THIRTY_DAYS, NINETY_DAYS, ONE_YEAR } from "./constants.mjs";
+import { gitCmd } from "./helpers.mjs";
+
+export function getFreshness(repoDir) {
+  const ts = gitCmd(
+    repoDir,
+    "log",
+    "-1",
+    "--format=%ct",
+    "--",
+    "CLAUDE.md",
+    "AGENTS.md",
+    ".claude/",
+  );
+  const parsed = Number(ts);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+export function relativeTime(ts) {
+  if (!ts) return "unknown";
+  const diff = Math.floor(Date.now() / 1000) - ts;
+  if (diff < ONE_DAY) return "today";
+  if (diff < TWO_DAYS) return "yesterday";
+  if (diff < THIRTY_DAYS) return `${Math.floor(diff / ONE_DAY)}d ago`;
+  if (diff < ONE_YEAR) return `${Math.floor(diff / THIRTY_DAYS)}mo ago`;
+  return `${Math.floor(diff / ONE_YEAR)}y ago`;
+}
+
+export function freshnessClass(ts) {
+  if (!ts) return "stale";
+  const diff = Math.floor(Date.now() / 1000) - ts;
+  if (diff < THIRTY_DAYS) return "fresh";
+  if (diff < NINETY_DAYS) return "aging";
+  return "stale";
+}

package/src/helpers.mjs

@@ -0,0 +1,42 @@
+import { execFileSync } from "child_process";
+import { HOME } from "./constants.mjs";
+
+export const esc = (s) =>
+  s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+
+export const shortPath = (p) => p.replace(HOME, "~");
+
+/** Format large token counts as MM/BB shorthand. Guards against undefined/NaN. */
+export function formatTokens(n) {
+  n = Number(n) || 0;
+  if (n >= 1_000_000_000) return `${(n / 1_000_000_000).toFixed(1)}B tokens`;
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M tokens`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K tokens`;
+  return `${n} tokens`;
+}
+
+/** Run a git command safely using execFileSync (no shell injection). */
+export function gitCmd(repoDir, ...args) {
+  try {
+    return execFileSync("git", ["-C", repoDir, ...args], {
+      encoding: "utf8",
+      timeout: 10_000,
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+export function anonymizePath(p) {
+  return p
+    .replace(/^\/Users\/[^/]+\//, "~/")
+    .replace(/^\/home\/[^/]+\//, "~/")
+    .replace(/^C:\\Users\\[^\\]+\\/, "~\\")
+    .replace(/^C:\/Users\/[^/]+\//, "~/");
+}