claude-mission-control 1.19.0 → 1.21.0

package/lib/collector.js

@@ -7,7 +7,7 @@ const { readQuota } = require('./quota');
 const { fetchOauthUsage } = require('./usage');
 const { readRegistry } = require('./registry');
 const { refreshHistory, activityBuckets, weekHourHeat } = require('./history');
-const { scanAllTranscripts, scanFile, groupByProject, sessionTitle, combinedUsage, combinedDays, dailyCostSeries, subagentSummary, usageBreakdown, dayKey, reasonText, contextSummary, toolSummary } = require('./transcripts');
+const { scanAllTranscripts, scanFile, groupByProject, sessionTitle, sessionKind, combinedUsage, combinedDays, dailyCostSeries, subagentSummary, usageBreakdown, dayKey, reasonText, contextSummary, toolSummary } = require('./transcripts');
 const { collectGitStatus } = require('./gitstatus');
 const { friendlyName } = require('./names');
 const { isIgnored } = require('./ignore');
@@ -277,6 +277,7 @@ class Collector {
     const liveByProject = new Set(
       this.raw.live.map((s) => worktreeRoot(s.cwd).root.toLowerCase())
     );
+    const liveIds = new Set(this.raw.live.map((s) => s.sessionId));
 
     const projects = [];
     for (const p of this.projectPaths()) {
@@ -287,6 +288,15 @@ class Collector {
       const git = this.raw.git.get(p) || null;
 
       const sessionMetas = group ? group.sessions : [];
+      // Automated and empty sessions still count toward spend and activity;
+      // they just don't take up rows in the card.
+      const shown = [];
+      const hidden = { automated: 0, empty: 0 };
+      for (const m of sessionMetas) {
+        const kind = sessionKind(m, liveIds.has(m.sessionId));
+        if (kind) hidden[kind]++;
+        else shown.push(m);
+      }
       const lastActivityAt = Math.max(
         sessionMetas[0] ? sessionMetas[0].lastActivityAt : 0,
         hist ? hist.lastTimestamp : 0,
@@ -309,7 +319,8 @@ class Collector {
             Date.now() - m.lastActivityAt < SPEND_WINDOW_MS ? sum + estimateCost(combinedUsage(m), pricing) : sum,
           0
         ),
-        sessions: sessionMetas.slice(0, SESSIONS_PER_PROJECT).map((m) => {
+        hidden,
+        sessions: shown.slice(0, SESSIONS_PER_PROJECT).map((m) => {
           const { title, source } = sessionTitle(m, sessionNames);
           return {
             sessionId: m.sessionId,
@@ -508,7 +519,6 @@ class Collector {
     const forecast = this.limitForecast();
 
     // Background jobs, live or finished, with any worktree work at risk.
-    const liveIds = new Set(this.raw.live.map((s) => s.sessionId));
     const jobWt = this.raw.jobWt || new Map();
     const jobsOut = jobs.map((j) => ({
       jobId: j.jobId,
@@ -543,6 +553,7 @@ class Collector {
         sessionId: m.sessionId,
         title,
         titleSource: source,
+        kind: sessionKind(m, this.raw.live.some((s) => s.sessionId === m.sessionId)),
         estCost: estimateCost(combinedUsage(m), pricing),
         assumed: costReport(combinedUsage(m), pricing).assumedModels.length > 0,
         awaySummary: m.awaySummary,

package/lib/transcripts.js

@@ -128,6 +128,7 @@ async function scanFile(abs, sessionIdFromName) {
     awaySummaryAt: null,
     aiTitle: null,
     waitingReason: null,
+    entrypoint: null,
   };
 
   // Head: first ~40 lines; the first line can be queue-operation without cwd.
@@ -148,6 +149,9 @@ async function scanFile(abs, sessionIdFromName) {
       const t = Date.parse(rec.timestamp);
       if (!Number.isNaN(t)) meta.startedAt = t;
     }
+    if (meta.entrypoint === null && rec.type === 'user' && typeof rec.entrypoint === 'string') {
+      meta.entrypoint = rec.entrypoint;
+    }
     if (meta.firstUserPrompt === null) {
       const text = extractUserText(rec);
       if (text) meta.firstUserPrompt = text.slice(0, 120);
@@ -573,6 +577,16 @@ function combinedUsage(meta) {
   return mergeUsage(mergeUsage({}, meta.usage), meta.subagentUsage);
 }
 
+// Sessions nobody needs in a project list. 'automated': a one-shot claude -p
+// run (recap and summarizer tools, plugin probes). 'empty': opened and closed
+// without ever calling the model — only /clear, /exit and the like. A live
+// session is never empty; it may just not have had its first reply yet.
+function sessionKind(meta, isLive = false) {
+  if (meta.entrypoint === 'sdk-cli') return 'automated';
+  if (!isLive && !Object.keys(combinedUsage(meta)).length) return 'empty';
+  return null;
+}
+
 // Cost breakdown for the transcript viewer, from the meta the collector
 // already holds — never re-reads the file. `context` and `tools` are
 // filled by the scanner once the context-pressure batch lands.
@@ -671,7 +685,7 @@ function groupByProject(sessions) {
 }
 
 module.exports = {
-  scanAllTranscripts, scanFile, groupByProject, sessionTitle, combinedUsage, mergeUsage,
+  scanAllTranscripts, scanFile, groupByProject, sessionTitle, sessionKind, combinedUsage, mergeUsage,
   scanLine, mergeDays, combinedDays, dailyCostSeries, subagentSummary, usageBreakdown, dayKey, contextSummary, toolSummary,
   waitingReason, reasonText, shouldReadMeta, TOOL_RING,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mission-control",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "Local dashboard for Claude Code: live sessions, transcripts, costs, git status — all your projects in one place.",
   "main": "server.js",
   "bin": {

package/public/index.html

@@ -350,6 +350,17 @@
     }
     .sessions li:hover > .acts, .sessions li:focus-within > .acts { pointer-events: auto; }
   }
+  .hidden-note {
+    align-self: flex-start; margin: 6px 0 4px; padding: 2px 0;
+    border: none; background: none; cursor: pointer;
+    font: 12px var(--ui-font); color: var(--faint);
+  }
+  .hidden-note:hover { color: var(--accent); }
+  .hidden-note:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 3px; }
+  .sessions + .hidden-note { border-top: 1px solid var(--line); align-self: stretch; text-align: left; padding-top: 8px; margin-top: 0; }
+  .d-noise { margin-top: 10px; }
+  .d-noise > summary { cursor: pointer; color: var(--faint); font-size: 12.5px; padding: 4px 0; }
+  .d-noise > summary:hover { color: var(--ink); }
   .card .new-btn { font-size: 16px; line-height: 1; padding: 2px 7px; color: var(--faint); }
   .card .new-btn:hover { color: var(--accent); }
 
@@ -939,6 +950,34 @@
   #palette-list li.sel .pl { color: var(--accent); }
   #palette-empty { color: var(--faint); font-size: 12px; padding: 12px 16px; }
 
+  /* ---------- first-run guide ---------- */
+  #guide {
+    background: var(--surface); border: 1px solid var(--line); border-radius: 10px;
+    padding: 16px 18px 14px; margin-bottom: 22px;
+  }
+  #guide .g-head { display: flex; align-items: baseline; gap: 12px; margin-bottom: 12px; }
+  #guide .g-head h2 { font-size: 14px; font-weight: 600; }
+  #guide .g-head .g-sub { color: var(--faint); font-size: 12.5px; }
+  #guide .g-head .spacer { flex: 1; }
+  #guide .g-done {
+    font: 500 12.5px var(--ui-font); color: var(--amber-ink); background: var(--accent);
+    border: none; border-radius: 6px; padding: 5px 12px; cursor: pointer;
+  }
+  #guide .g-done:focus-visible { outline: 2px solid var(--ink); outline-offset: 2px; }
+  #guide .g-grid { display: grid; gap: 12px 24px; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); }
+  #guide .g-item { font-size: 13px; color: var(--muted); line-height: 1.5; }
+  #guide .g-item b { display: block; color: var(--ink); font-weight: 600; margin-bottom: 4px; }
+  #guide .g-lamps { gap: 6px; }
+  #guide .g-lamps li { align-items: flex-start; }
+  #guide .g-lamps .flap { flex: none; min-width: 84px; justify-content: center; }
+  #guide kbd {
+    font-size: 11.5px; color: var(--ink); background: var(--surface2);
+    border: 1px solid var(--line); border-bottom-width: 2px; border-radius: 4px; padding: 0 5px;
+  }
+  #guide .g-icons { list-style: none; padding: 0; margin: 0; display: grid; gap: 3px; }
+  #guide .g-icons li { display: flex; align-items: center; gap: 8px; }
+  #guide .g-icons svg { flex: none; color: var(--ink); }
+
   /* welcome card for fresh installs */
   #welcome {
     grid-column: 1 / -1; background: var(--surface); border: 1px solid var(--line);
@@ -965,7 +1004,7 @@
     header .spacer, #open-pref-wrap { display: none; } /* opening terminals is a desk thing; still in settings */
     #quota { order: 10; flex: 1 1 100%; flex-wrap: wrap; gap: 8px 14px; }
     .meter .bar { width: 52px; }
-    #live { padding: 12px 16px; }
+    #live { padding: 12px 16px; position: static; } /* a sticky rail would cover most of a phone screen */
     main { padding: 14px 16px; }
     .dep-row { grid-template-columns: 1fr; padding: 10px 12px; }
     .dep-proj { font-size: 15px; }
@@ -1020,6 +1059,7 @@
 
 <section id="live"></section>
 <main>
+  <section id="guide" hidden aria-label="How to read this board"></section>
   <div id="pinned" hidden></div>
   <div id="git-attn" hidden></div>
   <details id="digest" open>
@@ -1373,6 +1413,13 @@ function liveCard(s) {
   </div>`;
 }
 
+// "3 automated runs, 1 empty session" — the rows a card or drawer folds away.
+function hiddenLabel(h) {
+  const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
+  return [h.automated && plural(h.automated, 'automated run'), h.empty && plural(h.empty, 'empty session')]
+    .filter(Boolean).join(', ');
+}
+
 function projectCard(p) {
   const sessions = p.sessions.length
     ? `<ul class="sessions">${p.sessions.map((sess) => `
@@ -1383,7 +1430,12 @@ function projectCard(p) {
           <span class="s-when">${relTime(sess.lastActivityAt)}</span>
           <span class="acts">${renameBtn(sess.sessionId, sess.title)}${openBtn(sess.sessionId)}${copyBtn(sess.resumeCommand)}</span>
         </li>`).join('')}</ul>`
-    : '<div class="none-yet">No sessions recorded.</div>';
+    : '';
+  const hiddenTxt = p.hidden ? hiddenLabel(p.hidden) : '';
+  const hiddenNote = hiddenTxt
+    ? `<button class="hidden-note" data-detail="${esc(p.path)}" data-detail-name="${esc(p.name)}" title="One-shot claude -p runs and sessions closed without a prompt. Open the project to see them.">${esc(hiddenTxt)} hidden</button>`
+    : '';
+  const empty = !p.sessions.length && !hiddenTxt ? '<div class="none-yet">No sessions recorded.</div>' : '';
   return `<div class="card">
     <div class="head">
       ${p.isLive ? '<span class="live-dot" title="session running"></span>' : ''}
@@ -1396,7 +1448,7 @@ function projectCard(p) {
       ${costChip(p.spend7d, { cls: 'badge', after: ' in 7d' })}
       <span class="when" title="${esc(p.path)}">${relTime(p.lastActivityAt)}</span>
     </div>
-    ${sessions}
+    ${sessions}${empty}${hiddenNote}
   </div>`;
 }
 
@@ -1591,7 +1643,8 @@ function render(state) {
   const now = Date.now();
   const active = [], dormant = [];
   for (const p of state.projects || []) {
-    const isDormant = !p.isLive && (!p.lastActivityAt || now - p.lastActivityAt > DORMANT_MS);
+    const noiseOnly = !p.sessions.length && p.hidden && (p.hidden.automated || p.hidden.empty);
+    const isDormant = !p.isLive && (noiseOnly || !p.lastActivityAt || now - p.lastActivityAt > DORMANT_MS);
     (isDormant ? dormant : active).push(p);
   }
   patch($('#grid'), active.length || dormant.length
@@ -1599,7 +1652,7 @@ function render(state) {
     : `<div id="welcome">
         <h2><span class="tilde">❯</span> Welcome to Claude Mission Control</h2>
         <p>No Claude Code projects found yet. Run <code>claude</code> in any folder and it appears here automatically — live status, transcripts, git state, costs, the lot.</p>
-        <p>Tip: press <code>⌘K</code> to jump anywhere, <code>/</code> to search, and click ⚙ for settings.</p>
+        <p>Tip: press <code>⌘K</code> to jump anywhere, <code>/</code> to search, and <code>?</code> for a quick guide.</p>
       </div>`);
   const d = $('#dormant');
   d.hidden = dormant.length === 0;
@@ -1851,8 +1904,7 @@ function toolsetHtml(t, projectPath) {
 function renderDetail(d, name) {
   $('#d-title').textContent = name;
   $('#d-path').textContent = d.path;
-  const sessions = d.sessions.length
-    ? `<ul class="d-sessions">${d.sessions.map((s) => `
+  const sessionRow = (s) => `
         <li>
           <span class="s-title" data-session="${esc(s.sessionId)}" title="${esc(titleTip(s.model))}">${
             s.worktree ? `<span class="wt mono">⎇ ${esc(s.worktree)}</span> ` : ''}${esc(s.title)}</span>${noteMark(s)}
@@ -1860,7 +1912,16 @@ function renderDetail(d, name) {
           ${costChip(s.estCost, { assumed: s.assumed })}
           <span class="s-when">${relTime(s.lastActivityAt)}</span>
           <span class="acts">${renameBtn(s.sessionId, s.title)}${openBtn(s.sessionId)}${copyBtn(s.resumeCommand)}</span>
-        </li>`).join('')}</ul>`
+        </li>`;
+  const real = d.sessions.filter((s) => !s.kind);
+  const noise = d.sessions.filter((s) => s.kind);
+  const noiseTxt = hiddenLabel({
+    automated: noise.filter((s) => s.kind === 'automated').length,
+    empty: noise.filter((s) => s.kind === 'empty').length,
+  });
+  const sessions = d.sessions.length
+    ? (real.length ? `<ul class="d-sessions">${real.map(sessionRow).join('')}</ul>` : '') +
+      (noise.length ? `<details class="d-noise"><summary>${esc(noiseTxt)}</summary><ul class="d-sessions">${noise.map(sessionRow).join('')}</ul></details>` : '')
     : null;
   const caps = [...d.skills, ...d.agents.map((a) => ({ ...a, name: `agent: ${a.name}` })),
     ...d.commands.map((c) => ({ ...c, name: `/${c.name}` }))];
@@ -1897,7 +1958,7 @@ function renderDetail(d, name) {
   const tsOff = ts ? KINDS.reduce((n, k) => n + (ts[k] || []).filter((r) => !r.enabled).length, 0) : 0;
   $('#d-body').innerHTML =
     muteBtn +
-    dSection(`Sessions — ${d.sessions.length}`, sessions, 'No sessions recorded.') +
+    dSection(`Sessions — ${d.sessions.filter((s) => !s.kind).length}`, sessions, 'No sessions recorded.') +
     dSection(`What changed — last ${(d.commits || []).length} commits`, commitRows ? commitSummaryLine(d.commitSummary) + `<ul class="d-sessions">${commitRows}</ul>` : null, 'No git history here.') +
     dSection('CLAUDE.md', d.claudeMd.length ? dFiles(d.claudeMd, 'name') : null, 'No CLAUDE.md — sessions here start without project instructions.') +
     dSection(`Memory — ${d.memory.length} file${d.memory.length === 1 ? '' : 's'}`, d.memory.length ? dFiles(d.memory, 'name') : null, 'No memory yet.') +
@@ -3147,7 +3208,7 @@ document.addEventListener('click', async (e) => {
 
 document.addEventListener('click', (e) => {
   const el = e.target.closest('[data-detail]');
-  if (el) openDetail(el.dataset.detail, el.textContent);
+  if (el) openDetail(el.dataset.detail, el.dataset.detailName || el.textContent);
 });
 $('#d-close').addEventListener('click', closeDetail);
 $('#drawer-backdrop').addEventListener('click', closeDetail);
@@ -3729,6 +3790,7 @@ function paletteItems(q) {
   const items = [];
   const st = lastState || { projects: [], liveSessions: [] };
   items.push({ k: '⚙', label: 'Settings', hint: 'rename, hide, terminal, notifications', run: openSettings });
+  items.push({ k: '?', label: 'Show the guide', hint: 'what the lamps, rows and buttons do', run: () => { showGuide(true, true); window.scrollTo({ top: 0 }); } });
   items.push({ k: '▦', label: 'Mission Control', hint: 'every live session at once', run: openMissionControl });
   items.push({ k: '⬢', label: 'Hive', hint: 'live sessions as characters · who is winning', run: openHive });
   items.push({ k: '★', label: 'Hall of Fame', hint: 'your best sessions by award · share cards', run: () => openFame() });
@@ -3832,6 +3894,58 @@ document.addEventListener('keydown', (e) => {
   }
 });
 
+// ---------- first-run guide: shown until dismissed, back with ? or the palette ----------
+const isMac = /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);
+function guideSeen() { try { return localStorage.getItem('guideSeen') === '1'; } catch { return true; } }
+function renderGuide() {
+  const icon = (id) => $(`#${id} svg`)?.outerHTML || '';
+  const mod = isMac ? '⌘' : 'Ctrl';
+  return `<div class="g-head">
+      <h2>How to read this board</h2>
+      <span class="g-sub">Press <kbd>?</kbd> to bring this back.</span>
+      <span class="spacer"></span>
+      <button class="g-done" id="guide-done">Got it</button>
+    </div>
+    <div class="g-grid">
+      <div class="g-item"><b>Status lamps</b>
+        <ul class="g-icons g-lamps">
+          <li><span class="flap st st-waiting">needs you</span> Claude is waiting on you. What it's asking shows under the title.</li>
+          <li><span class="flap st st-busy">busy</span> Claude is working.</li>
+        </ul></div>
+      <div class="g-item"><b>Sessions</b>
+        Click a session title to read its transcript, live if it's running. Hover a row to rename it, open it in your terminal, or copy its resume command.</div>
+      <div class="g-item"><b>Find anything</b>
+        <kbd>${mod}</kbd> <kbd>K</kbd> jumps to any project, session or view. <kbd>/</kbd> searches inside every transcript. Click a project name for its details.</div>
+      <div class="g-item"><b>Top-right buttons</b>
+        <ul class="g-icons">
+          <li>${icon('mc-btn')} Mission Control: every live session side by side</li>
+          <li>${icon('hive-btn')} Hive: live sessions ranked, plus Hall of Fame</li>
+          <li>${icon('bell-btn')} Catch up on what happened while you were away</li>
+          <li>${icon('gear')} Settings, themes and your phone view</li>
+        </ul></div>
+    </div>`;
+}
+function showGuide(show, focus = false) {
+  const g = $('#guide');
+  if (show) {
+    g.innerHTML = renderGuide();
+    g.hidden = false;
+    if (focus) $('#guide-done').focus({ preventScroll: true });
+  } else g.hidden = true;
+}
+document.addEventListener('click', (e) => {
+  if (!e.target.closest('#guide-done')) return;
+  try { localStorage.setItem('guideSeen', '1'); } catch {}
+  showGuide(false);
+});
+document.addEventListener('keydown', (e) => {
+  if (e.key !== '?' || e.metaKey || e.ctrlKey || /^(INPUT|TEXTAREA|SELECT)$/.test(document.activeElement?.tagName || '')) return;
+  e.preventDefault();
+  showGuide($('#guide').hidden, true);
+  if (!$('#guide').hidden) window.scrollTo({ top: 0 });
+});
+if (!guideSeen()) showGuide(true);
+
 poll();
 connect();
 setInterval(poll, 60_000);