agy-insights 0.7.3 → 0.8.0

package/README.es.md

@@ -36,7 +36,7 @@ npx agy-insights
 npx agy-insights@latest --text
 ```
 
-`@latest` hace que npx compruebe cada vez si hay una versión nueva. Sin él, una copia instalada globalmente (`npm install -g`) o en el proyecto actual tiene prioridad y no se actualiza nunca. Para fijar una versión concreta: `npx agy-insights@0.7.3`.
+`@latest` hace que npx compruebe cada vez si hay una versión nueva. Sin él, una copia instalada globalmente (`npm install -g`) o en el proyecto actual tiene prioridad y no se actualiza nunca. Para fijar una versión concreta: `npx agy-insights@0.8.0`.
 
 **Instalándolo globalmente:**
 
@@ -61,7 +61,7 @@ Y ejecútalo con `node agy-insights/agy-insights.js` en lugar de `npx agy-insigh
 npx agy-insights
 ```
 
-Analiza todo tu historial (todas las conversaciones que guarde agy, sin límite de fecha), guarda un informe HTML en la carpeta temporal y lo abre en el navegador. En el informe puedes cambiar entre todo el historial y los últimos 90, 30 o 7 días: los totales, la gráfica, los hallazgos y las tablas siguen el periodo elegido.
+Analiza todo tu historial (todas las conversaciones que guarde agy, sin límite de fecha), guarda un informe HTML en la carpeta temporal y lo abre en el navegador. En el informe puedes cambiar entre todo el historial y los últimos 90 o 30 días, o esta semana (desde el lunes): los totales, la gráfica, los hallazgos y las tablas siguen el periodo elegido.
 
 | Para… | Ejecuta |
 |---|---|
@@ -82,7 +82,7 @@ El informe da dos cifras:
 
 ## Leer el informe
 
-Arriba están el selector de periodo y los totales. Después, una gráfica de **consumo de tokens por día** (por semana si el historial pasa de ~4 meses) para ver la evolución; pasa el ratón por una columna para ver sus cifras, o abre «Ver como tabla». Después, **Modelos y esfuerzo**: llamadas y tokens reales por modelo y nivel de esfuerzo (por ejemplo Gemini 3.8 Flash · Alto), con los tokens por llamada, para ver cuánto cuesta un esfuerzo mayor. Debajo, **Qué está pasando** reúne los hallazgos; al final, el detalle por proyecto, tipo de fichero, carpeta, fichero, herramienta y comando. El proyecto de cada fichero se detecta por su carpeta `.git`.
+Arriba están el selector de periodo y los totales. Después, una gráfica de **consumo de tokens por día** (por semana si el historial pasa de ~4 meses) para ver la evolución. Cámbiala a **Por llamada** para ver los tokens medios de cada llamada al modelo: el total sube y baja según cuánto hayas trabajado, mientras que por llamada solo baja si cada llamada lleva menos contexto, así que es la que muestra si un cambio ha servido. Pasa el ratón por una columna para ver sus cifras, o abre «Ver como tabla». Después, **Modelos y esfuerzo**: llamadas y tokens reales por modelo y nivel de esfuerzo (por ejemplo Gemini 3.8 Flash · Alto), con los tokens por llamada, para ver cuánto cuesta un esfuerzo mayor. Debajo, **Qué está pasando** reúne los hallazgos; al final, el detalle por proyecto, tipo de fichero, carpeta, fichero, herramienta y comando. El proyecto de cada fichero se detecta por su carpeta `.git`.
 
 | Hallazgo | Qué significa | Qué hacer |
 |---|---|---|

package/README.md

@@ -36,7 +36,7 @@ npx agy-insights
 npx agy-insights@latest --text
 ```
 
-`@latest` makes npx check for the newest version every time. Without it, a copy installed globally (`npm install -g`) or in the current project takes precedence and is never updated. To pin a version instead: `npx agy-insights@0.7.3`.
+`@latest` makes npx check for the newest version every time. Without it, a copy installed globally (`npm install -g`) or in the current project takes precedence and is never updated. To pin a version instead: `npx agy-insights@0.8.0`.
 
 **Globally:**
 
@@ -61,7 +61,7 @@ Then run it with `node agy-insights/agy-insights.js` instead of `npx agy-insight
 npx agy-insights
 ```
 
-Analyzes your whole history (every conversation agy has kept, with no date limit), saves an HTML report in the temp folder and opens it in the browser. In the report you can switch between the whole history and the last 90, 30 or 7 days: totals, chart, findings and tables all follow the selected period.
+Analyzes your whole history (every conversation agy has kept, with no date limit), saves an HTML report in the temp folder and opens it in the browser. In the report you can switch between the whole history and the last 90 or 30 days, or this week (since Monday): totals, chart, findings and tables all follow the selected period.
 
 | To… | Run |
 |---|---|
@@ -82,7 +82,7 @@ The report gives two figures:
 
 ## Reading the report
 
-At the top, the period selector and the totals. Then a chart of **token usage per day** (per week when the history spans more than ~4 months), to see how usage evolves; hover a column for its figures, or open "View as table". Next, **Models and effort**: calls and real tokens per model and effort level (for example Gemini 3.8 Flash · High), including tokens per call, so you can see what a higher effort costs. Below, **What's happening** lists the findings; at the end, the details by project, file type, folder, file, tool and command. The project of each file is detected through its `.git` folder.
+At the top, the period selector and the totals. Then a chart of **token usage per day** (per week when the history spans more than ~4 months), to see how usage evolves. Switch it to **Per call** to see mean tokens per model call: the total follows how much you worked, while per call drops only when each call carries less context, so it is the one that shows whether a change paid off. Hover a column for its figures, or open "View as table". Next, **Models and effort**: calls and real tokens per model and effort level (for example Gemini 3.8 Flash · High), including tokens per call, so you can see what a higher effort costs. Below, **What's happening** lists the findings; at the end, the details by project, file type, folder, file, tool and command. The project of each file is detected through its `.git` folder.
 
 | Finding | What it means | What to do |
 |---|---|---|

package/agy-insights.js

@@ -98,7 +98,15 @@ function debugModels(r) {
 }
 
 // Periods the HTML report can switch to, besides the whole history.
-const PRESET_DAYS = [90, 30, 7];
+const PRESET_DAYS = [90, 30];
+
+// This Monday at local midnight.
+function weekStart() {
+  const d = new Date();
+  d.setHours(0, 0, 0, 0);
+  d.setDate(d.getDate() - ((d.getDay() + 6) % 7));
+  return d.getTime();
+}
 
 async function main() {
   const argv = process.argv.slice(2);
@@ -144,6 +152,8 @@ async function main() {
       const x = await run(Date.now() - days * 24 * 60 * 60 * 1000);
       views.push({ key: `d${days}`, label: t.report.rangeDays(days), r: x, found: find(x) });
     }
+    const week = await run(weekStart());
+    views.push({ key: 'week', label: t.report.rangeWeek, r: week, found: find(week) });
   }
   fs.writeFileSync(out, report.htmlViews(views, { scope: opts.project }));
   console.log(t.done(r.conversations, found.length, out));

package/docs/how-it-works.md

@@ -39,7 +39,7 @@ It is undocumented; this is what has been observed in `agy` 1.4.x.
 
 Each `transcript.jsonl` line also has `created_at` (ISO time). A conversation is dated by the first and last of those; without a transcript, by the `.db` file's last write. `--since` / `--days` keep a conversation when its last activity falls inside the period, and skip the rest before opening them. `../conversation_summaries.db` has one row per conversation: its short `title` (or `preview` in older ones) names each session in the report instead of its id; `last_modified_time` is not used. If the file is missing, sessions are shown by id. Each model call's `created_at` also puts its tokens on a local day (`r.daily`), which feeds the usage chart.
 
-The HTML report holds one view per period (whole history, last 90, 30 and 7 days): `agy-insights.js` runs `analyze()` and `findings()` once per period and `report.htmlViews()` renders them all, so switching in the browser needs no analysis code in the page and every number agrees with its period. The chart is inline SVG; its color (`--series`) is checked for contrast, chroma and lightness against both surfaces.
+The HTML report holds one view per period (whole history, last 90 and 30 days, this week since Monday): `agy-insights.js` runs `analyze()` and `findings()` once per period and `report.htmlViews()` renders them all, so switching in the browser needs no analysis code in the page and every number agrees with its period. The chart is inline SVG; its color (`--series`) is checked for contrast, chroma and lightness against both surfaces.
 
 `lib/history.js` does not depend on a protobuf schema. It walks the message, collects every string, and treats as a tool call any JSON preceded (within 3 strings) by a `snake_case` name. That way it survives minor format changes. If there are more than 50 steps and no recognized call, it sets `formatUnrecognized` and the report warns about it.
 

package/lib/i18n.js

@@ -142,12 +142,19 @@ Options:
     filterLabel: 'Period',
     rangeAll: 'All history',
     rangeDays: (n) => `Last ${n} days`,
+    rangeWeek: 'This week',
     chartTitleDay: 'Token usage per day',
     chartTitleWeek: 'Token usage per week',
     chartHint: 'Real tokens (input + output) of the model calls. Hover a column for details.',
     chartTable: 'View as table',
-    chartCols: ['Day', 'Tokens', 'With cache', 'Calls'],
-    chartColsWeek: ['Week of', 'Tokens', 'With cache', 'Calls'],
+    chartModeLabel: 'Show',
+    chartModeTotal: 'Total',
+    chartModeCall: 'Per call',
+    chartHintCall: 'Mean tokens (input + output) per model call. Unlike the total, it doesn\'t depend on how much you used the agent: it drops when each call carries less context (shorter sessions, filtered command output), so it shows whether a change worked.',
+    perCallTip: (n) => `${n} tokens per call`,
+    noActivity: 'No activity',
+    chartCols: ['Day', 'Tokens', 'With cache', 'Calls', 'Per call'],
+    chartColsWeek: ['Week of', 'Tokens', 'With cache', 'Calls', 'Per call'],
     chartCalls: (n) => plural(n, 'call', 'calls'),
     weekOf: (d) => `week of ${d}`,
     withCacheShort: 'with cache',
@@ -311,12 +318,19 @@ Opciones:
     filterLabel: 'Periodo',
     rangeAll: 'Todo el historial',
     rangeDays: (n) => `Últimos ${n} días`,
+    rangeWeek: 'Esta semana',
     chartTitleDay: 'Consumo de tokens por día',
     chartTitleWeek: 'Consumo de tokens por semana',
     chartHint: 'Tokens reales (entrada + salida) de las llamadas al modelo. Pasa el ratón por una columna para ver el detalle.',
     chartTable: 'Ver como tabla',
-    chartCols: ['Día', 'Tokens', 'Con caché', 'Llamadas'],
-    chartColsWeek: ['Semana del', 'Tokens', 'Con caché', 'Llamadas'],
+    chartModeLabel: 'Mostrar',
+    chartModeTotal: 'Total',
+    chartModeCall: 'Por llamada',
+    chartHintCall: 'Tokens medios (entrada + salida) por llamada al modelo. A diferencia del total, no depende de cuánto hayas usado el agente: baja cuando cada llamada lleva menos contexto (sesiones más cortas, salidas de comandos filtradas), así que muestra si un cambio ha funcionado.',
+    perCallTip: (n) => `${n} tokens por llamada`,
+    noActivity: 'Sin actividad',
+    chartCols: ['Día', 'Tokens', 'Con caché', 'Llamadas', 'Por llamada'],
+    chartColsWeek: ['Semana del', 'Tokens', 'Con caché', 'Llamadas', 'Por llamada'],
     chartCalls: (n) => plural(n, 'llamada', 'llamadas'),
     weekOf: (d) => `semana del ${d}`,
     withCacheShort: 'con caché',

package/lib/report.js

@@ -115,12 +115,33 @@ function buckets(r) {
   return { weekly, rows: [...byKey.values()] };
 }
 
+// Mean tokens per call: unlike the total, it doesn't follow how much the agent was used that day.
+const perCall = (x) => (x.calls ? x.billed / x.calls : 0);
+
 function chart(r) {
   const b = buckets(r);
   if (!b) return '';
+  const title = b.weekly ? t.report.chartTitleWeek : t.report.chartTitleDay;
+  const rows = b.rows.filter((x) => x.calls);
+  return `<section class="chart">
+    <h2>${title}</h2>
+    <div class="mode" role="group" aria-label="${esc(t.report.chartModeLabel)}">
+      <button type="button" data-mode="total" aria-pressed="true">${t.report.chartModeTotal}</button><button type="button" data-mode="call" aria-pressed="false">${t.report.chartModeCall}</button></div>
+    <p class="hint" data-mode="total">${t.report.chartHint}</p>
+    <p class="hint" data-mode="call" hidden>${t.report.chartHintCall}</p>
+    <div class="plot" data-mode="total">${plot(b, (x) => x.billed, (x) => `${fmt(x.billed)} tokens`, (x) => `${fmt(x.billed + x.cache)} ${t.report.withCacheShort}`, title)}</div>
+    <div class="plot" data-mode="call" hidden>${plot(b, perCall, (x) => t.report.perCallTip(fmt(perCall(x))), (x) => `${fmt(perCall(x) + x.cache / x.calls)} ${t.report.withCacheShort}`, `${title} · ${t.report.chartModeCall}`)}</div>
+    <details><summary>${t.report.chartTable}</summary><div class="scroll"><table><thead><tr>${(b.weekly ? t.report.chartColsWeek : t.report.chartCols).map((c, i) => `<th${i ? ' class="num"' : ''}>${c}</th>`).join('')}</tr></thead><tbody>
+      ${rows.map((x) => `<tr><td>${esc(shortDate(x.date, true))}</td><td class="num">${fmt(x.billed)}</td><td class="num">${fmt(x.billed + x.cache)}</td><td class="num">${x.calls}</td><td class="num">${fmt(perCall(x))}</td></tr>`).join('')}
+    </tbody></table></div></details>
+  </section>`;
+}
+
+// One column chart of `value` per bucket; `tip` and `cache` are the tooltip's headline and cache line.
+function plot(b, value, tip, cache, label) {
   const W = 900, H = 240, m = { l: 56, r: 8, t: 12, b: 28 };
   const pw = W - m.l - m.r, ph = H - m.t - m.b;
-  const top = niceMax(Math.max(...b.rows.map((x) => x.billed)));
+  const top = niceMax(Math.max(...b.rows.map(value)));
   const band = pw / b.rows.length;
   const bw = Math.max(1, Math.min(24, band - 2));
   const y = (v) => m.t + ph - (v / top) * ph;
@@ -130,28 +151,20 @@ function chart(r) {
     <text x="${m.l - 8}" y="${y(v) + 4}" text-anchor="end" class="axis">${esc(compact(v))}</text>`).join('');
   // Rounded data end (4px), square at the baseline.
   const bars = b.rows.map((x, i) => {
-    const h = (x.billed / top) * ph;
+    const h = (value(x) / top) * ph;
     if (h <= 0) return '';
     const x0 = m.l + i * band + (band - bw) / 2, y0 = m.t + ph - h, rr = Math.min(4, h, bw / 2);
     return `<path class="col" d="M${x0},${m.t + ph}V${y0 + rr}Q${x0},${y0} ${x0 + rr},${y0}H${x0 + bw - rr}Q${x0 + bw},${y0} ${x0 + bw},${y0 + rr}V${m.t + ph}Z"/>`;
   }).join('');
   // Hit targets: the whole band, so a 2px column is as easy to hover as a 24px one.
   const hits = b.rows.map((x, i) => `<rect class="hit" x="${m.l + i * band}" y="${m.t}" width="${band}" height="${ph}"
-    data-when="${esc(when(x))}" data-v="${esc(fmt(x.billed))}" data-c="${esc(fmt(x.billed + x.cache))}" data-n="${esc(t.report.chartCalls(x.calls))}"/>`).join('');
+    data-when="${esc(when(x))}" data-v="${esc(x.calls ? tip(x) : t.report.noActivity)}" data-c="${esc(x.calls ? cache(x) : '')}" data-n="${esc(x.calls ? t.report.chartCalls(x.calls) : '')}"/>`).join('');
   const every = Math.max(1, Math.ceil(b.rows.length / 6));
   // A date every few columns, plus the last one when it isn't crowded by the previous label.
   const last = b.rows.length - 1;
   const ticks = b.rows.map((x, i) => (i % every === 0 || (i === last && last % every >= every / 2)) && `<text x="${i === 0 && band < 40 ? m.l : i === last && band < 40 ? W - m.r : m.l + i * band + band / 2}" y="${H - 8}" text-anchor="${i === 0 && band < 40 ? 'start' : i === last && band < 40 ? 'end' : 'middle'}" class="axis">${esc(shortDate(x.date))}</text>`).filter(Boolean).join('');
 
-  const rows = b.rows.filter((x) => x.calls);
-  return `<section class="chart">
-    <h2>${b.weekly ? t.report.chartTitleWeek : t.report.chartTitleDay}</h2>
-    <p class="hint">${t.report.chartHint}</p>
-    <div class="plot"><svg viewBox="0 0 ${W} ${H}" role="img" aria-label="${esc(b.weekly ? t.report.chartTitleWeek : t.report.chartTitleDay)}">${grid}${bars}${ticks}${hits}</svg></div>
-    <details><summary>${t.report.chartTable}</summary><div class="scroll"><table><thead><tr>${(b.weekly ? t.report.chartColsWeek : t.report.chartCols).map((c, i) => `<th${i ? ' class="num"' : ''}>${c}</th>`).join('')}</tr></thead><tbody>
-      ${rows.map((x) => `<tr><td>${esc(shortDate(x.date, true))}</td><td class="num">${fmt(x.billed)}</td><td class="num">${fmt(x.billed + x.cache)}</td><td class="num">${x.calls}</td></tr>`).join('')}
-    </tbody></table></div></details>
-  </section>`;
+  return `<svg viewBox="0 0 ${W} ${H}" role="img" aria-label="${esc(label)}">${grid}${bars}${ticks}${hits}</svg>`;
 }
 
 // --- Page ---
@@ -219,6 +232,12 @@ function htmlViews(views, { scope }) {
   .filter button:hover { background: var(--accent-soft); }
   .filter button[aria-pressed="true"] { background: var(--accent); border-color: var(--accent); color: var(--surface); font-weight: 600; }
   .filter button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+  .mode { display: inline-flex; margin: 0 0 0 12px; vertical-align: 3px; border: 1px solid var(--line); border-radius: 6px; overflow: hidden; }
+  .mode button { font: 13px system-ui, sans-serif; color: var(--fg); background: var(--surface); border: 0; padding: 3px 10px; cursor: pointer; }
+  .mode button + button { border-left: 1px solid var(--line); }
+  .mode button:hover { background: var(--accent-soft); }
+  .mode button[aria-pressed="true"] { background: var(--accent-soft); color: var(--accent); font-weight: 600; }
+  .mode button:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }
   .tiles { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: 12px; margin: 16px 0 20px; }
   .tiles div { background: var(--surface); border: 1px solid var(--line); border-radius: 8px; padding: 12px 14px; }
   .tiles b { display: block; font-size: 24px; font-variant-numeric: tabular-nums; } .tiles span { color: var(--muted); font-size: 14px; }
@@ -271,6 +290,13 @@ function htmlViews(views, { scope }) {
       for (const s of document.querySelectorAll('.view')) s.hidden = s.dataset.view !== v.dataset.view;
       return;
     }
+    // Chart mode: the same in every period, so switching periods keeps it.
+    const m = e.target.closest('.mode button');
+    if (m) {
+      for (const b of document.querySelectorAll('.mode button')) b.setAttribute('aria-pressed', String(b.dataset.mode === m.dataset.mode));
+      for (const p of document.querySelectorAll('.chart [data-mode]:not(button)')) p.hidden = p.dataset.mode !== m.dataset.mode;
+      return;
+    }
     const b = e.target.closest('.copy'); if (!b) return;
     const pre = b.parentElement.querySelector('pre');
     const ok = () => { b.textContent = ${JSON.stringify(t.report.copied)}; setTimeout(() => (b.textContent = ${JSON.stringify(t.report.copy)}), 1500); };
@@ -285,9 +311,10 @@ function htmlViews(views, { scope }) {
     const h = e.target.closest && e.target.closest('.hit');
     if (!h) { tip.hidden = true; return; }
     const [v, when, rest] = tip.children;
-    v.textContent = h.dataset.v + ' tokens';
+    v.textContent = h.dataset.v;
     when.textContent = h.dataset.when;
-    rest.textContent = h.dataset.n + ' · ' + h.dataset.c + ' ' + ${JSON.stringify(t.report.withCacheShort)};
+    rest.textContent = h.dataset.c ? h.dataset.n + ' · ' + h.dataset.c : h.dataset.n;
+    rest.hidden = !rest.textContent;
     tip.hidden = false;
     const x = Math.min(e.clientX + 14, innerWidth - tip.offsetWidth - 8);
     tip.style.left = x + 'px';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-insights",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Measures Antigravity CLI token usage and shows which context is sent repeatedly or needlessly, in English or Spanish. Run: npx agy-insights@latest",
   "license": "MIT",
   "keywords": [