agy-insights 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miguel González
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,169 @@
+# agy-insights
+
+[English](README.md) · **Español**
+
+Te muestra qué contexto le estás mandando a **Antigravity** de forma repetida o innecesaria, a partir del historial que Antigravity CLI guarda en tu equipo. Tú decides qué hacer con ello.
+
+- Se ejecuta solo en tu máquina y no envía nada a ningún sitio.
+- No cambia nada: te dice qué pegar y dónde, y lo haces tú si quieres.
+- Solo propone mecanismos oficiales de Antigravity.
+- Funciona con cualquier editor, en Windows, macOS y Linux.
+
+```sh
+npx agy-insights          # informe HTML en el navegador
+npx agy-insights --text   # resumen en la terminal
+```
+
+Solo necesitas Node.js 20 o superior y haber usado Antigravity CLI (`agy`) en el equipo. La salida sale en español o en inglés según el idioma del sistema; puedes forzarlo con `--lang es` o `--lang en`.
+
+## Por qué
+
+Cada fichero que lee el agente y cada salida de comando entra en el contexto y se reenvía en los turnos siguientes de la conversación. La cuota es una bolsa común, así que cada lectura innecesaria la gasta para todos. Esta herramienta te enseña dónde se va ese contexto: relecturas, carpetas de compilación, salidas de tests enormes y sesiones demasiado largas.
+
+## Requisitos
+
+- **Node.js 20 o superior** (`node --version`).
+- Haber usado **Antigravity CLI** (`agy`) en este equipo. El historial está en `~/.gemini/antigravity-cli/conversations` (en Windows, `%USERPROFILE%\.gemini\antigravity-cli\conversations`).
+
+## Instalar
+
+No tiene dependencias. Elige una forma:
+
+**Con `npx`, sin instalar nada:**
+
+```sh
+npx agy-insights
+npx agy-insights --text
+```
+
+Para fijar una versión: `npx agy-insights@0.4.0`.
+
+**Instalándolo globalmente:**
+
+```sh
+npm install -g agy-insights
+agy-insights
+```
+
+**Clonando el repositorio:**
+
+```sh
+git clone https://github.com/migohe14/agy-insights.git
+```
+
+Y ejecútalo con `node agy-insights/agy-insights.js` en lugar de `npx agy-insights`. Para actualizar: `git pull` dentro de la carpeta.
+
+## Usar
+
+```sh
+npx agy-insights
+```
+
+Analiza todo tu historial, guarda un informe HTML en la carpeta temporal y lo abre en el navegador.
+
+| Para… | Ejecuta |
+|---|---|
+| Ver solo un proyecto | `npx agy-insights --project C:\dev\mi-proyecto` |
+| Ver el proyecto de la carpeta actual | `npx agy-insights --project .` |
+| Un resumen en la terminal | `npx agy-insights --text` |
+| El resumen con rutas y exclusiones | `npx agy-insights --text --paths` |
+| Un mapa del proyecto para pegar en `AGENTS.md` (carpetas, ficheros grandes, carpetas generadas; ~20 líneas aunque el repo sea grande) | `npx agy-insights --map --project <carpeta>` |
+| Elegir el idioma (español o inglés) | `npx agy-insights --lang es` |
+| Guardar el informe en otro sitio | `npx agy-insights --out informe.html --no-open` |
+| Ver todas las opciones | `npx agy-insights --help` |
+
+El informe da dos cifras:
+
+- **Consumo real**: los tokens que Antigravity anota en el registro de cada conversación (`~/.gemini/antigravity-cli/brain/<id>/.system_generated/logs/transcript.jsonl`), subagentes incluidos. Se muestra sin caché y con caché, porque no sabemos si la cuota cuenta igual la caché. Es la cifra que sirve para comparar entre compañeros.
+- **«~tokens»**: estimados a partir del tamaño guardado de cada paso. Sirven para comparar qué ficheros, carpetas o comandos pesan más, pero se quedan cortos frente al consumo real, porque cada llamada al modelo vuelve a enviar el contexto acumulado.
+
+## Leer el informe
+
+Arriba están los totales. 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 |
+|---|---|---|
+| El agente vuelve a leer lo que ya tenía | Lee otra vez un trozo de fichero que ya estaba en la conversación | Sesiones más cortas, una por tarea, o `/compact`. No excluyas el fichero: lo necesita. |
+| Ficheros generados, compilados o de dependencias | Lecturas de `bin/`, `obj/`, `dist/`, `node_modules`, migraciones, lockfiles o logs | Si no hacían falta, exclúyelos (ver abajo) |
+| Los mismos ficheros entran en muchas sesiones | Un fichero se lee en varias conversaciones distintas | Si es código central es normal; si es grande, dile al agente qué parte mirar |
+| Comandos con salidas muy largas | La salida de tests o builds entra entera | Pide ejecutar solo el test o proyecto afectado |
+| Sesiones muy largas | Todo lo acumulado se reenvía en cada turno | Una conversación nueva por tarea |
+
+## Excluir algo
+
+Despliega **Cómo excluirlo** en una propuesta. Verás el fichero exacto, dónde va el texto y un botón **Copiar**. Hay tres opciones, de más a menos fuerte:
+
+### 1. Denegar la lectura (permiso de Antigravity)
+
+Es lo único que impide de verdad que el agente lea una ruta. Usa los [permisos oficiales](https://antigravity.google/docs/permissions).
+
+1. Abre `~/.gemini/antigravity-cli/settings.json` (en Windows, `%USERPROFILE%\.gemini\antigravity-cli\settings.json`).
+2. Pega la regla dentro de `"permissions"` → `"deny"`. Si no existen, créalas; si existen, añade la regla sin borrar nada:
+
+   ```json
+   {
+     "model": "Gemini 3.8 Flash (Medium)",
+     "permissions": {
+       "deny": [
+         "read_file(C:\\dev\\mi-proyecto\\src\\Infra\\obj)"
+       ]
+     }
+   }
+   ```
+
+3. Guarda y reinicia `agy`.
+
+Denegar la lectura de una ruta también impide escribir en ella, y la regla vale para todos tus proyectos. Úsala para carpetas que el agente no deba tocar nunca, como salidas de compilación.
+
+### 2. `.antigravityignore`
+
+Es el fichero de exclusión de Antigravity, en la raíz del proyecto. Su efecto no está documentado: está confirmado que oculta los ficheros del autocompletado con `@`, pero no que impida al agente leerlos.
+
+### 3. Regla en `AGENTS.md`
+
+Una línea en el `AGENTS.md` del proyecto, pidiendo al modelo que no lea algo o que limite una salida. Es una indicación, no un bloqueo. Las reglas se envían en cada petición y también gastan tokens, así que mantenlas cortas. `AGENTS.md` suele estar en el repositorio del equipo: revisa el cambio antes de subirlo.
+
+## Configurar
+
+Copia `agy-insights.example.json` a `~/.agy-insights.json` (o pásalo con `--config`) y ajústalo. Es tu configuración personal:
+
+| Clave | Para qué sirve | Por defecto |
+|---|---|---|
+| `lang` | Idioma de la salida: `es` o `en` (`--lang` tiene prioridad) | el del sistema |
+| `conversationsDir` | Otra carpeta de historial | la de Antigravity CLI |
+| `customKinds` | Tipos de fichero propios: `{ "regex": "etiqueta" }` | ninguno |
+| `crossSessionMin` | A partir de cuántas conversaciones avisa de un fichero repetido | 3 |
+| `heavyOutputTokens` | A partir de qué tamaño medio avisa de un comando | 2000 |
+| `longSessionTokens` | A partir de qué tamaño avisa de una sesión larga | 100000 |
+
+## Privacidad
+
+- Todo se calcula en tu equipo; no se envía nada.
+- El historial se lee desde una copia temporal y nunca se modifica.
+- No escribe en `~/.gemini`, no instala hooks ni plugins y no toca tu `.gitignore` ni tus proyectos.
+- Lo único que escribe es el informe HTML, en la carpeta temporal o donde digas con `--out`.
+- El informe contiene rutas de tus proyectos. No lo compartas sin revisarlo.
+- **No compartas los ficheros `.db` del historial**: contienen el código que leyó el agente.
+
+## Deshacer
+
+- **Permiso**: borra la línea `read_file(…)` de `"deny"` en `settings.json` y reinicia `agy`.
+- **.antigravityignore y AGENTS.md**: borra las líneas que añadiste.
+
+## Problemas frecuentes
+
+**«No hay conversaciones»**. Si usaste `--project`, puede que trabajaras con Antigravity desde otra carpeta: prueba sin `--project`. Si tampoco aparecen, comprueba que existe la carpeta del historial.
+
+**«No se reconoce el formato del historial»**. Probablemente una versión nueva de Antigravity ha cambiado cómo guarda las conversaciones. Ejecuta `npx agy-insights@latest`; si sigue igual, [abre una incidencia](https://github.com/migohe14/agy-insights/issues).
+
+**Uso la app o el IDE de Antigravity, no el CLI**. Por ahora solo se lee el historial del CLI.
+
+**El navegador no se abre**. La ruta del informe aparece en la terminal; ábrela a mano.
+
+## Estado
+
+Versión piloto. El formato del historial de Antigravity no está documentado, así que algunos datos pueden fallar con versiones nuevas. Si ves algo raro, [abre una incidencia](https://github.com/migohe14/agy-insights/issues). Para contribuir, mira [docs/how-it-works.md](docs/how-it-works.md) (en inglés).
+
+## Licencia
+
+[MIT](LICENSE)

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# agy-insights
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [Español](README.es.md)
+
+Shows which context you are sending to **Antigravity** repeatedly or needlessly, based on the history Antigravity CLI keeps on your machine. You decide what to do about it.
+
+- Runs only on your machine and sends nothing anywhere.
+- Changes nothing: it tells you what to paste and where, and you do it if you want.
+- Only proposes official Antigravity mechanisms.
+- Works with any editor, on Windows, macOS and Linux.
+
+```sh
+npx agy-insights          # HTML report in the browser
+npx agy-insights --text   # summary in the terminal
+```
+
+All you need is Node.js 20 or later and to have used Antigravity CLI (`agy`) on this machine. The output is in English or Spanish, following your system language; force it with `--lang en` or `--lang es`.
+
+## Why
+
+Every file the agent reads and every command output enters the context and is resent on the following turns of the conversation. Quota is a shared pool, so every unnecessary read spends it for everyone. This tool shows you where that context goes: re-reads, build folders, huge test outputs and sessions that run too long.
+
+## Requirements
+
+- **Node.js 20 or later** (`node --version`).
+- Having used **Antigravity CLI** (`agy`) on this machine. The history lives in `~/.gemini/antigravity-cli/conversations` (on Windows, `%USERPROFILE%\.gemini\antigravity-cli\conversations`).
+
+## Install
+
+It has no dependencies. Pick one:
+
+**With `npx`, nothing to install:**
+
+```sh
+npx agy-insights
+npx agy-insights --text
+```
+
+To pin a version: `npx agy-insights@0.4.0`.
+
+**Globally:**
+
+```sh
+npm install -g agy-insights
+agy-insights
+```
+
+**From the repository:**
+
+```sh
+git clone https://github.com/migohe14/agy-insights.git
+```
+
+Then run it with `node agy-insights/agy-insights.js` instead of `npx agy-insights`. To update: `git pull` inside the folder.
+
+## Usage
+
+```sh
+npx agy-insights
+```
+
+Analyzes your whole history, saves an HTML report in the temp folder and opens it in the browser.
+
+| To… | Run |
+|---|---|
+| See only one project | `npx agy-insights --project C:\dev\my-project` |
+| See the project in the current folder | `npx agy-insights --project .` |
+| Get a summary in the terminal | `npx agy-insights --text` |
+| Get the summary with paths and exclusions | `npx agy-insights --text --paths` |
+| Get a project map to paste into `AGENTS.md` (folders, large files, generated folders; ~20 lines even for a large repo) | `npx agy-insights --map --project <folder>` |
+| Choose the language (English or Spanish) | `npx agy-insights --lang es` |
+| Save the report somewhere else | `npx agy-insights --out report.html --no-open` |
+| See all options | `npx agy-insights --help` |
+
+The report gives two figures:
+
+- **Real usage**: the tokens Antigravity records in each conversation's log (`~/.gemini/antigravity-cli/brain/<id>/.system_generated/logs/transcript.jsonl`), subagents included. It is shown with and without cache, because it is unknown whether the quota counts cache the same way. This is the figure to compare between teammates.
+- **"~tokens"**: estimated from the stored size of each step. Useful to compare which files, folders or commands weigh the most, but they fall short of real usage, because every model call resends the accumulated context.
+
+## Reading the report
+
+The totals are at the top. 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 |
+|---|---|---|
+| The agent re-reads what it already had | It reads again a chunk of a file that was already in the conversation | Shorter sessions, one per task, or `/compact`. Don't exclude the file: the agent needs it. |
+| Generated, build or dependency files are being read | Reads from `bin/`, `obj/`, `dist/`, `node_modules`, migrations, lockfiles or logs | If they weren't needed, exclude them (see below) |
+| The same files enter many sessions | A file is read in several different conversations | Normal for core code; if it is large, tell the agent which part to look at |
+| Commands with very long output | The full output of tests or builds enters the context | Ask it to run only the affected test or project |
+| Very long sessions | Everything accumulated is resent on every turn | A new conversation per task |
+
+## Excluding something
+
+Expand **How to exclude it** on a proposal. You'll see the exact file, where the text goes and a **Copy** button. There are three options, from strongest to weakest:
+
+### 1. Deny reading it (Antigravity permission)
+
+This is the only thing that actually stops the agent from reading a path. It uses the [official permissions](https://antigravity.google/docs/permissions).
+
+1. Open `~/.gemini/antigravity-cli/settings.json` (on Windows, `%USERPROFILE%\.gemini\antigravity-cli\settings.json`).
+2. Paste the rule inside `"permissions"` → `"deny"`. Create them if they don't exist; if they do, add the rule without removing anything:
+
+   ```json
+   {
+     "model": "Gemini 3.8 Flash (Medium)",
+     "permissions": {
+       "deny": [
+         "read_file(C:\\dev\\my-project\\src\\Infra\\obj)"
+       ]
+     }
+   }
+   ```
+
+3. Save and restart `agy`.
+
+Denying reads on a path also blocks writing to it, and the rule applies to all your projects. Use it for folders the agent should never touch, such as build output.
+
+### 2. `.antigravityignore`
+
+Antigravity's exclusion file, at the project root. Its effect is undocumented: it is confirmed to hide files from `@` completion, but not to stop the agent from reading them.
+
+### 3. A rule in `AGENTS.md`
+
+A line in the project's `AGENTS.md` asking the model not to read something or to limit an output. It is an instruction, not a block. Rules are sent with every request and cost tokens too, so keep them short. `AGENTS.md` usually lives in the team repository: review the change before pushing it.
+
+## Configuration
+
+Copy `agy-insights.example.json` to `~/.agy-insights.json` (or pass it with `--config`) and adjust it. It is your personal configuration:
+
+| Key | What it does | Default |
+|---|---|---|
+| `lang` | Output language: `en` or `es` (`--lang` takes precedence) | the system's |
+| `conversationsDir` | Another history folder | Antigravity CLI's |
+| `customKinds` | Your own file types: `{ "regex": "label" }` | none |
+| `crossSessionMin` | From how many conversations a repeated file is reported | 3 |
+| `heavyOutputTokens` | From what average size a command is reported | 2000 |
+| `longSessionTokens` | From what size a session is reported as long | 100000 |
+
+## Privacy
+
+- Everything is computed on your machine; nothing is sent.
+- The history is read from a temporary copy and never modified.
+- It does not write to `~/.gemini`, installs no hooks or plugins, and does not touch your `.gitignore` or your projects.
+- The only thing it writes is the HTML report, in the temp folder or wherever `--out` says.
+- The report contains paths from your projects. Review it before sharing.
+- **Don't share the history `.db` files**: they contain the code the agent read.
+
+## Undo
+
+- **Permission**: remove the `read_file(…)` line from `"deny"` in `settings.json` and restart `agy`.
+- **.antigravityignore and AGENTS.md**: remove the lines you added.
+
+## Troubleshooting
+
+**"No conversations"**. If you used `--project`, you may have worked with Antigravity from another folder: try without `--project`. If they still don't show up, check that the history folder exists.
+
+**"The history format is not recognized"**. A new Antigravity version has probably changed how it stores conversations. Run `npx agy-insights@latest`; if it persists, [open an issue](https://github.com/migohe14/agy-insights/issues).
+
+**I use the Antigravity app or IDE, not the CLI**. For now only the CLI history is read.
+
+**The browser doesn't open**. The report path is printed in the terminal; open it manually.
+
+## Status
+
+Pilot version. Antigravity's history format is undocumented, so some data may break with new versions. If you see something odd, [open an issue](https://github.com/migohe14/agy-insights/issues). To contribute, see [docs/how-it-works.md](docs/how-it-works.md).
+
+## License
+
+[MIT](LICENSE)

package/agy-insights.example.json

@@ -0,0 +1,10 @@
+{
+  "conversationsDir": "",
+  "customKinds": {
+    "/Legacy/": "legacy code",
+    "\\.resx$": "resources"
+  },
+  "crossSessionMin": 3,
+  "heavyOutputTokens": 2000,
+  "longSessionTokens": 100000
+}

package/agy-insights.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// agy-insights: shows which context is sent to Antigravity repeatedly or needlessly, from the local
+// Antigravity CLI history. Read-only: the only file it writes is the HTML report, in the temp folder
+// (or wherever --out says).
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+const { analyze, DEFAULT_DIR } = require('./lib/history');
+const { findings, DEFAULTS } = require('./lib/findings');
+const report = require('./lib/report');
+const { buildMap } = require('./lib/map');
+const { t, setLang, detect } = require('./lib/i18n');
+
+function parseArgs(argv) {
+  const opts = { open: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const value = () => {
+      if (i + 1 >= argv.length) fail(t.missingValue(a));
+      return argv[++i];
+    };
+    if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--project') opts.project = absolute(value());
+    else if (a === '--text') opts.text = true;
+    else if (a === '--paths') opts.paths = true;
+    else if (a === '--map') opts.map = true;
+    else if (a === '--out') opts.out = path.resolve(value());
+    else if (a === '--no-open') opts.open = false;
+    else if (a === '--dir') opts.dir = path.resolve(value());
+    else if (a === '--config') opts.config = path.resolve(value());
+    else if (a === '--lang') opts.lang = value();
+    else fail(t.unknownOption(a));
+  }
+  return opts;
+}
+
+// History paths may come from Windows ("C:\..."): keep those as they are on any OS.
+const absolute = (p) => (/^[A-Za-z]:[\\/]/.test(p) ? p : path.resolve(p));
+
+function fail(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+
+function loadConfig(file) {
+  const target = file || path.join(os.homedir(), '.agy-insights.json');
+  if (!fs.existsSync(target)) {
+    if (file) fail(t.configNotFound(file));
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(target, 'utf8'));
+  } catch (e) {
+    return fail(t.cannotRead(target, e.message));
+  }
+}
+
+function openInBrowser(file) {
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [file]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', file]]
+    : ['xdg-open', [file]];
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true }).on('error', () => {}).unref();
+  } catch { /* the path is printed anyway */ }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  // Language first, so that option errors are already in it.
+  if (!(argv.includes('--lang') && setLang(argv[argv.indexOf('--lang') + 1]))) setLang(detect());
+  const opts = parseArgs(argv);
+  if (opts.lang && !setLang(opts.lang)) fail(t.badLang(opts.lang));
+  if (opts.help) return console.log(t.help(DEFAULT_DIR));
+  const cfg = loadConfig(opts.config);
+  if (!opts.lang && cfg.lang && !setLang(cfg.lang)) fail(t.badLang(cfg.lang));
+
+  if (opts.map) opts.project = opts.project || process.cwd();
+  const r = await analyze({
+    dir: opts.dir || cfg.conversationsDir || DEFAULT_DIR,
+    workspaces: opts.project ? [opts.project] : [],
+    customKinds: cfg.customKinds || {},
+  });
+  if (opts.map) {
+    const m = buildMap(opts.project, { ...cfg.map, history: r.files });
+    console.log(m.block);
+    return console.error(t.mapDone(m.tokens, path.join(opts.project, 'AGENTS.md')));
+  }
+  const found = findings(r, {
+    crossSessionMin: cfg.crossSessionMin ?? DEFAULTS.crossSessionMin,
+    heavyOutputTokens: cfg.heavyOutputTokens ?? DEFAULTS.heavyOutputTokens,
+    longSessionTokens: cfg.longSessionTokens ?? DEFAULTS.longSessionTokens,
+  });
+
+  if (opts.text) return process.stdout.write(report.text(r, found, { scope: opts.project, paths: opts.paths }));
+
+  const stamp = new Date().toISOString().slice(0, 16).replace(/[-:T]/g, '');
+  const out = opts.out || path.join(os.tmpdir(), 'agy-insights', `${t.reportName}-${stamp}.html`);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, report.html(r, found, { scope: opts.project }));
+  console.log(t.done(r.conversations, found.length, out));
+  if (opts.open) openInBrowser(out);
+}
+
+main().catch((e) => fail(`Error: ${e.message}`));

package/docs/how-it-works.md

@@ -0,0 +1,98 @@
+# How it works
+
+For whoever maintains or extends agy-insights.
+
+## Principles
+
+Every change must respect them:
+
+1. **Read-only.** Nothing is written to `~/.gemini` or to the developer's projects. The history is copied to a temp folder before opening it, because `agy` keeps those databases open. The only thing written is the report.
+2. **The developer decides.** The tool proposes text to paste; it never applies it.
+3. **Only official Antigravity mechanisms** for exclusions: permissions (`read_file` in `permissions.deny`), `.antigravityignore` and rules in `AGENTS.md`. No hooks, plugins, `.gitignore` or `.ignore`.
+4. **Fail visibly.** If the history format changes, the report must say so instead of showing wrong data.
+5. **Nothing to install.** Only Node 20 or later; SQLite ships in `vendor/`.
+
+## Layout
+
+```
+agy-insights.js       command: options, configuration, writes the report and opens the browser
+lib/history.js        reads the history and aggregates reads, commands, projects and sessions
+lib/findings.js       turns the analysis into findings (the 5 detectors)
+lib/fixes.js          builds the text of each exclusion; writes nothing
+lib/map.js            project map for AGENTS.md (--map); writes nothing
+lib/i18n.js           every user-facing message, in English and Spanish, and language detection
+lib/report.js         HTML report (static, copy buttons only) and text summary
+vendor/sql.js/        SQLite in WebAssembly (version in VERSION, MIT license in LICENSE)
+test/fake-history.js  generates fake histories in the same format as real ones
+test/*.test.js        tests (node --test)
+```
+
+## The Antigravity CLI history
+
+It is undocumented; this is what has been observed in `agy` 1.4.x.
+
+- One SQLite database per conversation: `~/.gemini/antigravity-cli/conversations/<uuid>.db`, in WAL mode.
+- Table `steps`: one row per step. `step_payload` is a protobuf message. Tool calls store the name (`view_file`, `run_command`, `grep_search`…) followed by their JSON arguments, for example `{"AbsolutePath":"C:\\dev\\...\\X.cs","StartLine":301,"EndLine":380}`, preceded by a `call_NNN` id.
+- Each call takes two steps with the same id: the model response that requests it (`step_type` 15) and the result (`step_type` 132), which repeats name and arguments and adds the file content or command output. `lib/history.js` counts the call once per id and adds the size of both steps, which approximates what entered the context.
+- Table `gen_metadata`: configuration of each model call, including the model name.
+- Next to the history, `../brain/<id>/.system_generated/logs/transcript.jsonl`: one JSON line per step. `PLANNER_RESPONSE` lines are model calls and carry `input_tokens`, `cache_read_tokens` and `output_tokens`; failed steps have `status: "ERROR"`. Subagents have their own conversation and transcript. `realUsage()` in `lib/history.js` adds those figures up (it only reads the file). The total printed by `agy -p --output-format json` does not include subagents; this one does.
+
+`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.
+
+### SQLite
+
+- With Node 22.13 or later, `node:sqlite` is used, which also reads the `-wal` file.
+- With earlier versions, `sql.js` from `vendor/` is used. It doesn't read the `-wal`, so the last steps of an open conversation may be missing.
+
+To update `sql.js`: copy `dist/sql-wasm.js`, `dist/sql-wasm.wasm` and `LICENSE` from the new version of the npm package and update `VERSION`.
+
+### Projects
+
+The project of each file is detected by walking up its path until a folder with `.git` is found, if the path exists on the machine. With `--project`, that folder is used directly. Windows paths (`C:\...`) are normalized to `/` internally and returned with `\` in exclusions, because `agy` matches permission paths literally.
+
+## Languages
+
+All user-facing text lives in `lib/i18n.js`, in an `en` and an `es` table with the same keys (a test checks it). Modules read it through `t`, which always points at the current language. The language comes from `--lang`, then the `lang` config key, then the system locale (`LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE`, or `Intl`): Spanish if it starts with `es`, English otherwise. Numbers follow it too (`en-US` / `es-ES`).
+
+Built-in file kinds are stable ids (`build`, `logs`, `generated`, `code .cs`…) and are only turned into text when shown, with `kindLabel()`. Kinds from `customKinds` are shown as the user wrote them.
+
+To add a message, add it to both tables. To add a language, add a table and teach `detect()` to pick it.
+
+## Adding a file type
+
+In `lib/history.js`, function `kind()`, returning a new id and its label in both tables of `lib/i18n.js`. If it is a type that rarely needs to be read, also add it to `NON_SOURCE`, and its `.antigravityignore` patterns to `KIND_PATTERNS` in `lib/findings.js`. Each developer can add their own types without touching the code with `customKinds` in their configuration.
+
+## Adding a detector
+
+In `lib/findings.js`. A finding is `{ id, level: 'info' | 'warn', title, why, suggestion, tokens, items }`, and each `item` is `{ label, tokens, detail, fixes }`. `fixes` are built with `lib/fixes.js`. Never propose excluding source code: the agent needs it.
+
+Add a case to `test/fake-history.js` and a test.
+
+## Tests
+
+```sh
+npm test
+```
+
+They cover the analysis with a fake history, the five detectors, the rule format, that excluding source code is never proposed, that the history is not changed, project detection through `.git`, the unknown-format warning, HTML escaping, the project map and the full command. CI runs them on Linux, Windows and macOS with Node 20 (sql.js) and Node 22 (node:sqlite).
+
+To generate a sample history and try the report by hand:
+
+```sh
+node test/fake-history.js test/tmp/history
+node agy-insights.js --dir test/tmp/history
+```
+
+## npm package
+
+`package.json` defines the command (`bin`) and which files go into the package (`files`: the command, `lib/`, `vendor/`, `docs/` and the sample configuration; not the tests). It is published on the public npm registry as `agy-insights`. The package only contains the tool; the histories it analyzes stay on each user's machine.
+
+- **Try the package locally**: `npm pack`, then `npx --yes --package=./agy-insights-<version>.tgz agy-insights --help`.
+- **From the repository**, unpublished: `npx --yes github:migohe14/agy-insights`. With no dependencies and no build step, npm installs it straight from git.
+- **Release a version**: `npm version <patch|minor|major>` (updates `package.json` and creates the `v…` tag) and `git push --follow-tags`. The `.github/workflows/publish.yml` workflow runs the tests and `npm publish --provenance`. It needs the `NPM_TOKEN` secret in the GitHub repository (an npm *Automation* or *Granular* token with publish permission).
+
+## To do
+
+- Confirm with `agy` that a `read_file` `deny` rule blocks the read.
+- Test with real histories from several developers (Windows and macOS).
+- Also read the history of the Antigravity app and IDE, if they use the same format.