agy-insights 0.3.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.es.md +172 -0
- package/README.md +95 -77
- package/agy-insights.example.json +2 -2
- package/agy-insights.js +51 -28
- package/docs/how-it-works.md +102 -0
- package/lib/findings.js +45 -61
- package/lib/fixes.js +10 -9
- package/lib/history.js +84 -18
- package/lib/i18n.js +357 -0
- package/lib/map.js +8 -7
- package/lib/report.js +224 -59
- package/package.json +8 -4
- package/docs/como-funciona.md +0 -88
package/README.es.md
ADDED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
# agy-insights
|
|
2
|
+
|
|
3
|
+
[English](README.md) · **Español**
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
- Se ejecuta solo en tu máquina y no envía nada a ningún sitio.
|
|
8
|
+
- No cambia nada: te dice qué pegar y dónde, y lo haces tú si quieres.
|
|
9
|
+
- Solo propone mecanismos oficiales de Antigravity.
|
|
10
|
+
- Funciona con cualquier editor, en Windows, macOS y Linux.
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npx agy-insights@latest # informe HTML en el navegador
|
|
14
|
+
npx agy-insights@latest --text # resumen en la terminal
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
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`.
|
|
18
|
+
|
|
19
|
+
## Por qué
|
|
20
|
+
|
|
21
|
+
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.
|
|
22
|
+
|
|
23
|
+
## Requisitos
|
|
24
|
+
|
|
25
|
+
- **Node.js 20 o superior** (`node --version`).
|
|
26
|
+
- Haber usado **Antigravity CLI** (`agy`) en este equipo. El historial está en `~/.gemini/antigravity-cli/conversations` (en Windows, `%USERPROFILE%\.gemini\antigravity-cli\conversations`).
|
|
27
|
+
|
|
28
|
+
## Instalar
|
|
29
|
+
|
|
30
|
+
No tiene dependencias. Elige una forma:
|
|
31
|
+
|
|
32
|
+
**Con `npx`, sin instalar nada:**
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
npx agy-insights
|
|
36
|
+
npx agy-insights@latest --text
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`@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.0`.
|
|
40
|
+
|
|
41
|
+
**Instalándolo globalmente:**
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
npm install -g agy-insights
|
|
45
|
+
agy-insights
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Para actualizarlo: `npm install -g agy-insights@latest`.
|
|
49
|
+
|
|
50
|
+
**Clonando el repositorio:**
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
git clone https://github.com/migohe14/agy-insights.git
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Y ejecútalo con `node agy-insights/agy-insights.js` en lugar de `npx agy-insights@latest`. Para actualizar: `git pull` dentro de la carpeta.
|
|
57
|
+
|
|
58
|
+
## Usar
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
npx agy-insights
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
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.
|
|
65
|
+
|
|
66
|
+
| Para… | Ejecuta |
|
|
67
|
+
|---|---|
|
|
68
|
+
| Ver solo un proyecto | `npx agy-insights@latest --project C:\dev\mi-proyecto` |
|
|
69
|
+
| Ver el proyecto de la carpeta actual | `npx agy-insights@latest --project .` |
|
|
70
|
+
| Un resumen en la terminal | `npx agy-insights@latest --text` |
|
|
71
|
+
| El resumen con rutas y exclusiones | `npx agy-insights@latest --text --paths` |
|
|
72
|
+
| 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@latest --map --project <carpeta>` |
|
|
73
|
+
| Solo un periodo a medida (el informe ya no tiene selector de periodo) | `npx agy-insights@latest --since 2026-10-01` o `--days 14` |
|
|
74
|
+
| Elegir el idioma (español o inglés) | `npx agy-insights@latest --lang es` |
|
|
75
|
+
| Guardar el informe en otro sitio | `npx agy-insights@latest --out informe.html --no-open` |
|
|
76
|
+
| Ver todas las opciones | `npx agy-insights@latest --help` |
|
|
77
|
+
|
|
78
|
+
El informe da dos cifras:
|
|
79
|
+
|
|
80
|
+
- **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.
|
|
81
|
+
- **«~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.
|
|
82
|
+
|
|
83
|
+
## Leer el informe
|
|
84
|
+
|
|
85
|
+
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`.
|
|
86
|
+
|
|
87
|
+
| Hallazgo | Qué significa | Qué hacer |
|
|
88
|
+
|---|---|---|
|
|
89
|
+
| 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. |
|
|
90
|
+
| 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) |
|
|
91
|
+
| 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 |
|
|
92
|
+
| Comandos con salidas muy largas | La salida de tests o builds entra entera | Pide ejecutar solo el test o proyecto afectado |
|
|
93
|
+
| Sesiones muy largas | Todo lo acumulado se reenvía en cada turno | Una conversación nueva por tarea |
|
|
94
|
+
|
|
95
|
+
## Excluir algo
|
|
96
|
+
|
|
97
|
+
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:
|
|
98
|
+
|
|
99
|
+
### 1. Denegar la lectura (permiso de Antigravity)
|
|
100
|
+
|
|
101
|
+
Es lo único que impide de verdad que el agente lea una ruta. Usa los [permisos oficiales](https://antigravity.google/docs/permissions).
|
|
102
|
+
|
|
103
|
+
1. Abre `~/.gemini/antigravity-cli/settings.json` (en Windows, `%USERPROFILE%\.gemini\antigravity-cli\settings.json`).
|
|
104
|
+
2. Pega la regla dentro de `"permissions"` → `"deny"`. Si no existen, créalas; si existen, añade la regla sin borrar nada:
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"model": "Gemini 3.8 Flash (Medium)",
|
|
109
|
+
"permissions": {
|
|
110
|
+
"deny": [
|
|
111
|
+
"read_file(C:\\dev\\mi-proyecto\\src\\Infra\\obj)"
|
|
112
|
+
]
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
3. Guarda y reinicia `agy`.
|
|
118
|
+
|
|
119
|
+
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.
|
|
120
|
+
|
|
121
|
+
### 2. `.antigravityignore`
|
|
122
|
+
|
|
123
|
+
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.
|
|
124
|
+
|
|
125
|
+
### 3. Regla en `AGENTS.md`
|
|
126
|
+
|
|
127
|
+
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.
|
|
128
|
+
|
|
129
|
+
## Configurar
|
|
130
|
+
|
|
131
|
+
Copia `agy-insights.example.json` a `~/.agy-insights.json` (o pásalo con `--config`) y ajústalo. Es tu configuración personal:
|
|
132
|
+
|
|
133
|
+
| Clave | Para qué sirve | Por defecto |
|
|
134
|
+
|---|---|---|
|
|
135
|
+
| `lang` | Idioma de la salida: `es` o `en` (`--lang` tiene prioridad) | el del sistema |
|
|
136
|
+
| `conversationsDir` | Otra carpeta de historial | la de Antigravity CLI |
|
|
137
|
+
| `customKinds` | Tipos de fichero propios: `{ "regex": "etiqueta" }` | ninguno |
|
|
138
|
+
| `crossSessionMin` | A partir de cuántas conversaciones avisa de un fichero repetido | 3 |
|
|
139
|
+
| `heavyOutputTokens` | A partir de qué tamaño medio avisa de un comando | 2000 |
|
|
140
|
+
| `longSessionTokens` | A partir de qué tamaño avisa de una sesión larga | 100000 |
|
|
141
|
+
|
|
142
|
+
## Privacidad
|
|
143
|
+
|
|
144
|
+
- Todo se calcula en tu equipo; no se envía nada.
|
|
145
|
+
- El historial se lee desde una copia temporal y nunca se modifica.
|
|
146
|
+
- No escribe en `~/.gemini`, no instala hooks ni plugins y no toca tu `.gitignore` ni tus proyectos.
|
|
147
|
+
- Lo único que escribe es el informe HTML, en la carpeta temporal o donde digas con `--out`.
|
|
148
|
+
- El informe contiene rutas de tus proyectos. No lo compartas sin revisarlo.
|
|
149
|
+
- **No compartas los ficheros `.db` del historial**: contienen el código que leyó el agente.
|
|
150
|
+
|
|
151
|
+
## Deshacer
|
|
152
|
+
|
|
153
|
+
- **Permiso**: borra la línea `read_file(…)` de `"deny"` en `settings.json` y reinicia `agy`.
|
|
154
|
+
- **.antigravityignore y AGENTS.md**: borra las líneas que añadiste.
|
|
155
|
+
|
|
156
|
+
## Problemas frecuentes
|
|
157
|
+
|
|
158
|
+
**«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.
|
|
159
|
+
|
|
160
|
+
**«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).
|
|
161
|
+
|
|
162
|
+
**Uso la app o el IDE de Antigravity, no el CLI**. Por ahora solo se lee el historial del CLI.
|
|
163
|
+
|
|
164
|
+
**El navegador no se abre**. La ruta del informe aparece en la terminal; ábrela a mano.
|
|
165
|
+
|
|
166
|
+
## Estado
|
|
167
|
+
|
|
168
|
+
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).
|
|
169
|
+
|
|
170
|
+
## Licencia
|
|
171
|
+
|
|
172
|
+
[MIT](LICENSE)
|
package/README.md
CHANGED
|
@@ -1,154 +1,172 @@
|
|
|
1
1
|
# agy-insights
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**English** · [Español](README.es.md)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
- No cambia nada: te dice qué pegar y dónde, y lo haces tú si quieres.
|
|
7
|
-
- Solo propone mecanismos oficiales de Antigravity.
|
|
8
|
-
- Funciona con cualquier editor, en Windows, macOS y Linux.
|
|
5
|
+
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.
|
|
9
6
|
|
|
10
|
-
|
|
7
|
+
- Runs only on your machine and sends nothing anywhere.
|
|
8
|
+
- Changes nothing: it tells you what to paste and where, and you do it if you want.
|
|
9
|
+
- Only proposes official Antigravity mechanisms.
|
|
10
|
+
- Works with any editor, on Windows, macOS and Linux.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
```sh
|
|
13
|
+
npx agy-insights@latest # HTML report in the browser
|
|
14
|
+
npx agy-insights@latest --text # summary in the terminal
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
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`.
|
|
18
|
+
|
|
19
|
+
## Why
|
|
20
|
+
|
|
21
|
+
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.
|
|
13
22
|
|
|
14
|
-
##
|
|
23
|
+
## Requirements
|
|
15
24
|
|
|
16
|
-
- **Node.js 20
|
|
17
|
-
-
|
|
25
|
+
- **Node.js 20 or later** (`node --version`).
|
|
26
|
+
- Having used **Antigravity CLI** (`agy`) on this machine. The history lives in `~/.gemini/antigravity-cli/conversations` (on Windows, `%USERPROFILE%\.gemini\antigravity-cli\conversations`).
|
|
18
27
|
|
|
19
|
-
##
|
|
28
|
+
## Install
|
|
20
29
|
|
|
21
|
-
|
|
30
|
+
It has no dependencies. Pick one:
|
|
22
31
|
|
|
23
|
-
**
|
|
32
|
+
**With `npx`, nothing to install:**
|
|
24
33
|
|
|
25
34
|
```sh
|
|
26
35
|
npx agy-insights
|
|
27
|
-
npx agy-insights --text
|
|
36
|
+
npx agy-insights@latest --text
|
|
28
37
|
```
|
|
29
38
|
|
|
30
|
-
|
|
39
|
+
`@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.0`.
|
|
31
40
|
|
|
32
|
-
**
|
|
41
|
+
**Globally:**
|
|
33
42
|
|
|
34
43
|
```sh
|
|
35
44
|
npm install -g agy-insights
|
|
36
45
|
agy-insights
|
|
37
46
|
```
|
|
38
47
|
|
|
39
|
-
|
|
48
|
+
To update it: `npm install -g agy-insights@latest`.
|
|
49
|
+
|
|
50
|
+
**From the repository:**
|
|
40
51
|
|
|
41
52
|
```sh
|
|
42
53
|
git clone https://github.com/migohe14/agy-insights.git
|
|
43
54
|
```
|
|
44
55
|
|
|
45
|
-
|
|
56
|
+
Then run it with `node agy-insights/agy-insights.js` instead of `npx agy-insights@latest`. To update: `git pull` inside the folder.
|
|
46
57
|
|
|
47
|
-
##
|
|
58
|
+
## Usage
|
|
48
59
|
|
|
49
60
|
```sh
|
|
50
|
-
|
|
61
|
+
npx agy-insights
|
|
51
62
|
```
|
|
52
63
|
|
|
53
|
-
|
|
64
|
+
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.
|
|
54
65
|
|
|
55
|
-
|
|
|
66
|
+
| To… | Run |
|
|
56
67
|
|---|---|
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
|
|
|
60
|
-
|
|
|
61
|
-
|
|
|
62
|
-
|
|
|
63
|
-
|
|
|
68
|
+
| See only one project | `npx agy-insights@latest --project C:\dev\my-project` |
|
|
69
|
+
| See the project in the current folder | `npx agy-insights@latest --project .` |
|
|
70
|
+
| Get a summary in the terminal | `npx agy-insights@latest --text` |
|
|
71
|
+
| Get the summary with paths and exclusions | `npx agy-insights@latest --text --paths` |
|
|
72
|
+
| Get a project map to paste into `AGENTS.md` (folders, large files, generated folders; ~20 lines even for a large repo) | `npx agy-insights@latest --map --project <folder>` |
|
|
73
|
+
| Only a custom period (the report then has no period selector) | `npx agy-insights@latest --since 2026-10-01` or `--days 14` |
|
|
74
|
+
| Choose the language (English or Spanish) | `npx agy-insights@latest --lang es` |
|
|
75
|
+
| Save the report somewhere else | `npx agy-insights@latest --out report.html --no-open` |
|
|
76
|
+
| See all options | `npx agy-insights@latest --help` |
|
|
64
77
|
|
|
65
|
-
|
|
78
|
+
The report gives two figures:
|
|
66
79
|
|
|
67
|
-
- **
|
|
68
|
-
-
|
|
80
|
+
- **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.
|
|
81
|
+
- **"~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.
|
|
69
82
|
|
|
70
|
-
##
|
|
83
|
+
## Reading the report
|
|
71
84
|
|
|
72
|
-
|
|
85
|
+
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.
|
|
73
86
|
|
|
74
|
-
|
|
|
87
|
+
| Finding | What it means | What to do |
|
|
75
88
|
|---|---|---|
|
|
76
|
-
|
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
89
|
+
| 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. |
|
|
90
|
+
| 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) |
|
|
91
|
+
| 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 |
|
|
92
|
+
| 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 |
|
|
93
|
+
| Very long sessions | Everything accumulated is resent on every turn | A new conversation per task |
|
|
81
94
|
|
|
82
|
-
##
|
|
95
|
+
## Excluding something
|
|
83
96
|
|
|
84
|
-
|
|
97
|
+
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:
|
|
85
98
|
|
|
86
|
-
### 1.
|
|
99
|
+
### 1. Deny reading it (Antigravity permission)
|
|
87
100
|
|
|
88
|
-
|
|
101
|
+
This is the only thing that actually stops the agent from reading a path. It uses the [official permissions](https://antigravity.google/docs/permissions).
|
|
89
102
|
|
|
90
|
-
1.
|
|
91
|
-
2.
|
|
103
|
+
1. Open `~/.gemini/antigravity-cli/settings.json` (on Windows, `%USERPROFILE%\.gemini\antigravity-cli\settings.json`).
|
|
104
|
+
2. Paste the rule inside `"permissions"` → `"deny"`. Create them if they don't exist; if they do, add the rule without removing anything:
|
|
92
105
|
|
|
93
106
|
```json
|
|
94
107
|
{
|
|
95
108
|
"model": "Gemini 3.8 Flash (Medium)",
|
|
96
109
|
"permissions": {
|
|
97
110
|
"deny": [
|
|
98
|
-
"read_file(C:\\dev\\
|
|
111
|
+
"read_file(C:\\dev\\my-project\\src\\Infra\\obj)"
|
|
99
112
|
]
|
|
100
113
|
}
|
|
101
114
|
}
|
|
102
115
|
```
|
|
103
116
|
|
|
104
|
-
3.
|
|
117
|
+
3. Save and restart `agy`.
|
|
105
118
|
|
|
106
|
-
|
|
119
|
+
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.
|
|
107
120
|
|
|
108
121
|
### 2. `.antigravityignore`
|
|
109
122
|
|
|
110
|
-
|
|
123
|
+
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.
|
|
111
124
|
|
|
112
|
-
### 3.
|
|
125
|
+
### 3. A rule in `AGENTS.md`
|
|
113
126
|
|
|
114
|
-
|
|
127
|
+
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.
|
|
115
128
|
|
|
116
|
-
##
|
|
129
|
+
## Configuration
|
|
117
130
|
|
|
118
|
-
|
|
131
|
+
Copy `agy-insights.example.json` to `~/.agy-insights.json` (or pass it with `--config`) and adjust it. It is your personal configuration:
|
|
119
132
|
|
|
120
|
-
|
|
|
133
|
+
| Key | What it does | Default |
|
|
121
134
|
|---|---|---|
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
135
|
+
| `lang` | Output language: `en` or `es` (`--lang` takes precedence) | the system's |
|
|
136
|
+
| `conversationsDir` | Another history folder | Antigravity CLI's |
|
|
137
|
+
| `customKinds` | Your own file types: `{ "regex": "label" }` | none |
|
|
138
|
+
| `crossSessionMin` | From how many conversations a repeated file is reported | 3 |
|
|
139
|
+
| `heavyOutputTokens` | From what average size a command is reported | 2000 |
|
|
140
|
+
| `longSessionTokens` | From what size a session is reported as long | 100000 |
|
|
141
|
+
|
|
142
|
+
## Privacy
|
|
143
|
+
|
|
144
|
+
- Everything is computed on your machine; nothing is sent.
|
|
145
|
+
- The history is read from a temporary copy and never modified.
|
|
146
|
+
- It does not write to `~/.gemini`, installs no hooks or plugins, and does not touch your `.gitignore` or your projects.
|
|
147
|
+
- The only thing it writes is the HTML report, in the temp folder or wherever `--out` says.
|
|
148
|
+
- The report contains paths from your projects. Review it before sharing.
|
|
149
|
+
- **Don't share the history `.db` files**: they contain the code the agent read.
|
|
127
150
|
|
|
128
|
-
##
|
|
151
|
+
## Undo
|
|
129
152
|
|
|
130
|
-
-
|
|
131
|
-
-
|
|
132
|
-
- No escribe en `~/.gemini`, no instala hooks ni plugins y no toca tu `.gitignore` ni tus proyectos.
|
|
133
|
-
- Lo único que escribe es el informe HTML, en la carpeta temporal o donde digas con `--out`.
|
|
134
|
-
- El informe contiene rutas de tus proyectos. No lo compartas sin revisarlo.
|
|
135
|
-
- **No compartas los ficheros `.db` del historial**: contienen el código que leyó el agente, a menudo de cliente.
|
|
153
|
+
- **Permission**: remove the `read_file(…)` line from `"deny"` in `settings.json` and restart `agy`.
|
|
154
|
+
- **.antigravityignore and AGENTS.md**: remove the lines you added.
|
|
136
155
|
|
|
137
|
-
##
|
|
156
|
+
## Troubleshooting
|
|
138
157
|
|
|
139
|
-
|
|
140
|
-
- **.antigravityignore y AGENTS.md**: borra las líneas que añadiste.
|
|
158
|
+
**"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.
|
|
141
159
|
|
|
142
|
-
|
|
160
|
+
**"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).
|
|
143
161
|
|
|
144
|
-
|
|
162
|
+
**I use the Antigravity app or IDE, not the CLI**. For now only the CLI history is read.
|
|
145
163
|
|
|
146
|
-
|
|
164
|
+
**The browser doesn't open**. The report path is printed in the terminal; open it manually.
|
|
147
165
|
|
|
148
|
-
|
|
166
|
+
## Status
|
|
149
167
|
|
|
150
|
-
|
|
168
|
+
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).
|
|
151
169
|
|
|
152
|
-
##
|
|
170
|
+
## License
|
|
153
171
|
|
|
154
|
-
|
|
172
|
+
[MIT](LICENSE)
|
package/agy-insights.js
CHANGED
|
@@ -10,29 +10,14 @@ const { analyze, DEFAULT_DIR } = require('./lib/history');
|
|
|
10
10
|
const { findings, DEFAULTS } = require('./lib/findings');
|
|
11
11
|
const report = require('./lib/report');
|
|
12
12
|
const { buildMap } = require('./lib/map');
|
|
13
|
-
|
|
14
|
-
const HELP = `Uso: agy-insights [opciones] (o npx …, o node agy-insights.js)
|
|
15
|
-
|
|
16
|
-
Analiza tu historial de Antigravity CLI y abre un informe en el navegador.
|
|
17
|
-
|
|
18
|
-
Opciones:
|
|
19
|
-
--project <carpeta> Solo conversaciones que tocaron ese proyecto ("." = carpeta actual)
|
|
20
|
-
--text Resumen en la terminal en vez del informe HTML
|
|
21
|
-
--paths Con --text, muestra rutas y las exclusiones propuestas
|
|
22
|
-
--map Imprime un mapa del proyecto (--project, o la carpeta actual) para AGENTS.md
|
|
23
|
-
--out <fichero> Dónde guardar el informe HTML (por defecto, en la carpeta temporal)
|
|
24
|
-
--no-open No abrir el navegador
|
|
25
|
-
--dir <carpeta> Otra carpeta de historial (por defecto ${DEFAULT_DIR})
|
|
26
|
-
--config <fichero> Configuración (por defecto ~/.agy-insights.json si existe)
|
|
27
|
-
--help Esta ayuda
|
|
28
|
-
`;
|
|
13
|
+
const { t, setLang, detect } = require('./lib/i18n');
|
|
29
14
|
|
|
30
15
|
function parseArgs(argv) {
|
|
31
16
|
const opts = { open: true };
|
|
32
17
|
for (let i = 0; i < argv.length; i++) {
|
|
33
18
|
const a = argv[i];
|
|
34
19
|
const value = () => {
|
|
35
|
-
if (i + 1 >= argv.length) fail(
|
|
20
|
+
if (i + 1 >= argv.length) fail(t.missingValue(a));
|
|
36
21
|
return argv[++i];
|
|
37
22
|
};
|
|
38
23
|
if (a === '--help' || a === '-h') opts.help = true;
|
|
@@ -44,7 +29,10 @@ function parseArgs(argv) {
|
|
|
44
29
|
else if (a === '--no-open') opts.open = false;
|
|
45
30
|
else if (a === '--dir') opts.dir = path.resolve(value());
|
|
46
31
|
else if (a === '--config') opts.config = path.resolve(value());
|
|
47
|
-
else
|
|
32
|
+
else if (a === '--lang') opts.lang = value();
|
|
33
|
+
else if (a === '--since') opts.since = value();
|
|
34
|
+
else if (a === '--days') opts.days = value();
|
|
35
|
+
else fail(t.unknownOption(a));
|
|
48
36
|
}
|
|
49
37
|
return opts;
|
|
50
38
|
}
|
|
@@ -60,13 +48,13 @@ function fail(msg) {
|
|
|
60
48
|
function loadConfig(file) {
|
|
61
49
|
const target = file || path.join(os.homedir(), '.agy-insights.json');
|
|
62
50
|
if (!fs.existsSync(target)) {
|
|
63
|
-
if (file) fail(
|
|
51
|
+
if (file) fail(t.configNotFound(file));
|
|
64
52
|
return {};
|
|
65
53
|
}
|
|
66
54
|
try {
|
|
67
55
|
return JSON.parse(fs.readFileSync(target, 'utf8'));
|
|
68
56
|
} catch (e) {
|
|
69
|
-
return fail(
|
|
57
|
+
return fail(t.cannotRead(target, e.message));
|
|
70
58
|
}
|
|
71
59
|
}
|
|
72
60
|
|
|
@@ -79,35 +67,70 @@ function openInBrowser(file) {
|
|
|
79
67
|
} catch { /* the path is printed anyway */ }
|
|
80
68
|
}
|
|
81
69
|
|
|
70
|
+
// --since YYYY-MM-DD (local midnight) or --days n (n days back from now), as a time in ms; null for all.
|
|
71
|
+
function sinceTime({ since, days }) {
|
|
72
|
+
if (since) {
|
|
73
|
+
const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(since);
|
|
74
|
+
const d = m && new Date(+m[1], m[2] - 1, +m[3]);
|
|
75
|
+
if (!d || d.getMonth() !== m[2] - 1) fail(t.badDate(since));
|
|
76
|
+
return d.getTime();
|
|
77
|
+
}
|
|
78
|
+
if (days !== undefined) {
|
|
79
|
+
if (!/^\d+$/.test(days)) fail(t.badDays(days));
|
|
80
|
+
return Date.now() - Number(days) * 24 * 60 * 60 * 1000;
|
|
81
|
+
}
|
|
82
|
+
return null;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
// Periods the HTML report can switch to, besides the whole history.
|
|
86
|
+
const PRESET_DAYS = [90, 30, 7];
|
|
87
|
+
|
|
82
88
|
async function main() {
|
|
83
|
-
const
|
|
84
|
-
|
|
89
|
+
const argv = process.argv.slice(2);
|
|
90
|
+
// Language first, so that option errors are already in it.
|
|
91
|
+
if (!(argv.includes('--lang') && setLang(argv[argv.indexOf('--lang') + 1]))) setLang(detect());
|
|
92
|
+
const opts = parseArgs(argv);
|
|
93
|
+
if (opts.lang && !setLang(opts.lang)) fail(t.badLang(opts.lang));
|
|
94
|
+
if (opts.help) return console.log(t.help(DEFAULT_DIR));
|
|
85
95
|
const cfg = loadConfig(opts.config);
|
|
96
|
+
if (!opts.lang && cfg.lang && !setLang(cfg.lang)) fail(t.badLang(cfg.lang));
|
|
86
97
|
|
|
87
98
|
if (opts.map) opts.project = opts.project || process.cwd();
|
|
88
|
-
const
|
|
99
|
+
const since = sinceTime(opts);
|
|
100
|
+
const run = (from) => analyze({
|
|
101
|
+
since: from,
|
|
89
102
|
dir: opts.dir || cfg.conversationsDir || DEFAULT_DIR,
|
|
90
103
|
workspaces: opts.project ? [opts.project] : [],
|
|
91
104
|
customKinds: cfg.customKinds || {},
|
|
92
105
|
});
|
|
106
|
+
const r = await run(since);
|
|
93
107
|
if (opts.map) {
|
|
94
108
|
const m = buildMap(opts.project, { ...cfg.map, history: r.files });
|
|
95
109
|
console.log(m.block);
|
|
96
|
-
return console.error(
|
|
110
|
+
return console.error(t.mapDone(m.tokens, path.join(opts.project, 'AGENTS.md')));
|
|
97
111
|
}
|
|
98
|
-
const
|
|
112
|
+
const find = (x) => findings(x, {
|
|
99
113
|
crossSessionMin: cfg.crossSessionMin ?? DEFAULTS.crossSessionMin,
|
|
100
114
|
heavyOutputTokens: cfg.heavyOutputTokens ?? DEFAULTS.heavyOutputTokens,
|
|
101
115
|
longSessionTokens: cfg.longSessionTokens ?? DEFAULTS.longSessionTokens,
|
|
102
116
|
});
|
|
117
|
+
const found = find(r);
|
|
103
118
|
|
|
104
119
|
if (opts.text) return process.stdout.write(report.text(r, found, { scope: opts.project, paths: opts.paths }));
|
|
105
120
|
|
|
106
121
|
const stamp = new Date().toISOString().slice(0, 16).replace(/[-:T]/g, '');
|
|
107
|
-
const out = opts.out || path.join(os.tmpdir(), 'agy-insights',
|
|
122
|
+
const out = opts.out || path.join(os.tmpdir(), 'agy-insights', `${t.reportName}-${stamp}.html`);
|
|
108
123
|
fs.mkdirSync(path.dirname(out), { recursive: true });
|
|
109
|
-
|
|
110
|
-
|
|
124
|
+
// Whole history by default, plus the presets the page can switch to. With --since/--days, just that period.
|
|
125
|
+
const views = [{ key: 'all', label: since ? '' : t.report.rangeAll, r, found }];
|
|
126
|
+
if (!since && r.conversations) {
|
|
127
|
+
for (const days of PRESET_DAYS) {
|
|
128
|
+
const x = await run(Date.now() - days * 24 * 60 * 60 * 1000);
|
|
129
|
+
views.push({ key: `d${days}`, label: t.report.rangeDays(days), r: x, found: find(x) });
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
fs.writeFileSync(out, report.htmlViews(views, { scope: opts.project }));
|
|
133
|
+
console.log(t.done(r.conversations, found.length, out));
|
|
111
134
|
if (opts.open) openInBrowser(out);
|
|
112
135
|
}
|
|
113
136
|
|