1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
# claude-sesiones
Explorá todas las conversaciones de [Claude Code](https://claude.com/claude-code)
que tenés guardadas en la máquina: como tabla en la terminal, o como una página
HTML autocontenida que se abre con doble clic.
Español · **[English](README.md)** · Sin dependencias, solo biblioteca estándar.
```
# SESIÓN RUTA FECHA CUÁNDO MSG DUR ID
1 | Migrar el pool de conexiones a … /home/ana/api 16 ago hoy 4 9m 5d10f1ee
2 | Timeouts intermitentes en el he… /home/ana/api 16 ago hoy 2 3m 0f60f37a
3 | Reescribir el buscador con Fuse… /home/ana/web 15 ago ayer 7 18m b69c1fc2
4 | por qué tarda tanto npm ci /home/ana/web 13 ago hace 3d 1 <1m d4d2a5be
5 | sesión abierta sin mens… [vacía] /home/ana/infra 08 ago hace 1sem — <1m e0a4300e
5 sesiones · 3 proyectos · -s <nº> para leer una
```
## ⚠️ Tus transcripciones son privadas
`--json` y `--html` escriben **el texto completo de tus conversaciones**:
prompts, respuestas, rutas de archivos, nombres de ramas. El `sesiones.html` que
sale es una copia legible de todo lo que escribiste alguna vez en Claude Code.
No lo commitees, no lo subas, no lo pegues en un issue. El `.gitignore` del repo
ya excluye `sesiones.html` y `data.json`, pero el archivo lo cuidás vos.
## Instalación
Necesita Python 3.9 o más nuevo. Nada más.
```bash
pipx install git+https://github.com/ElvisClaros/claude-sesiones
```
O con pip, o directamente desde un clon:
```bash
pip install git+https://github.com/ElvisClaros/claude-sesiones
git clone https://github.com/ElvisClaros/claude-sesiones && cd claude-sesiones
python3 -m claude_sesiones # sin instalar nada
```
## Uso
```bash
claude-sesiones # tabla de todas las sesiones
claude-sesiones docker # filtra por título, ruta o rama
claude-sesiones -s 3 # lee el chat nº 3 de la tabla
claude-sesiones -s 5d10f1ee # lo mismo, por prefijo de UUID
claude-sesiones -g "port already" # busca dentro de las conversaciones
claude-sesiones -r 3 # imprime el comando para reanudarla
eval "$(claude-sesiones -r 3)" # …o la reanuda directamente
claude-sesiones --html --open # genera sesiones.html y lo abre
```
El número es la posición de la fila **en la tabla que estás viendo**, así que si
filtraste hay que repetir el filtro para leer esa fila:
```bash
claude-sesiones docker # muestra 3 resultados
claude-sesiones docker -s 2 # lee el 2º de esos tres
```
### Opciones
| Flag | Qué hace |
| --- | --- |
| `-s`, `--show REF` | Muestra un chat (índice de la tabla o prefijo de UUID). |
| `-r`, `--resume REF` | Imprime `cd <proyecto> && claude --resume <uuid>`. |
| `-g`, `--grep TEXTO` | Deja las sesiones cuya transcripción contenga `TEXTO`. |
| `-p`, `--project RUTA` | Deja las sesiones cuya ruta de proyecto contenga `RUTA`. |
| `-n`, `--limit N` | Solo las N más recientes. |
| `-E`, `--hide-empty` | Oculta las sesiones sin mensajes. |
| `--no-tools` | En el chat, oculta las llamadas a herramientas. |
| `--no-pager` | No manda el chat a `$PAGER`. |
| `--no-color` | Salida sin color (también respeta `NO_COLOR`). |
| `--json` | Vuelca todas las sesiones en JSON por stdout. |
| `--html [ARCHIVO]` | Genera la página autocontenida (por defecto `sesiones.html`). |
| `--template ARCHIVO` | Usa tu propio template para `--html`. |
| `--open` | Abre en el navegador lo que haya generado `--html`. |
| `--no-cache` | Ignora el caché y re-parsea todo. |
### Borrar sesiones
Es irreversible y pregunta antes, salvo que pases `-y`:
```bash
claude-sesiones --delete-empty --dry-run # qué borraría
claude-sesiones --delete-empty # borra las vacías
claude-sesiones -D 101 -D e0a4300e # borra sesiones puntuales
claude-sesiones -p /tmp --delete-empty # solo las vacías de ese proyecto
```
Avisa si alguno de los archivos se escribió en los últimos cinco minutos: es muy
probable que sea una sesión que Claude Code todavía tiene abierta, y que la
vuelva a escribir al cerrarse.
## La página HTML
`claude-sesiones --html` genera un único archivo con los datos adentro. Sin
servidor, sin red, sin paso de build: lo copiás a otra máquina y sigue andando.
- Búsqueda por título, ruta, rama o UUID, y opcionalmente dentro de las
transcripciones, mostrando el fragmento que coincide debajo de la fila.
- Filtro por proyecto, orden por cualquier columna, ocultar las vacías.
- Clic en una fila para leer la conversación en un panel lateral, con cercas de
código, títulos y una línea por herramienta usada.
- Botón para copiar el `cd … && claude --resume …` de cualquier sesión.
- Tema claro y oscuro, con un botón que recuerda cuál elegiste.
- Cada sesión tiene su propio fragmento de URL: `sesiones.html#5d10f1ee-…` abre
esa conversación directamente.
- Teclado: `/` o `Ctrl`+`K` enfoca el buscador, `Esc` lo limpia o cierra el lector.
Las fechas son relativas a **cuándo se leyeron los datos**, no a tu reloj, así
que "hoy" sigue queriendo decir lo que quería decir cuando generaste la página.
## Cómo funciona
Claude Code guarda una conversación por archivo, en formato JSON Lines:
```
~/.claude/projects/<ruta-del-proyecto-codificada>/<uuid>.jsonl
```
(Si moviste ese directorio, respeta `CLAUDE_CONFIG_DIR`.)
Cada línea es un evento. `claude-sesiones` los recorre y se queda con la
conversación: tus mensajes, las respuestas de Claude, y una línea por
herramienta usada, del estilo `Bash: git status`. A propósito **descarta lo que
devolvieron las herramientas**: son el 95 % de los bytes en disco y casi nada
del sentido.
Algunos detalles que conviene saber:
- **Títulos.** Claude genera uno durante la sesión (eventos `ai-title`); gana el
más reciente. Cuando falta, se usa lo primero que escribiste vos — y ahí se
nota, porque arranca en minúscula o suena a pregunta suelta.
- **Sesiones vacías** son las que se abrieron pero nunca recibieron un mensaje:
un `/resume` cancelado, un `/login`.
- **No interactivas** son `claude -p` con algo piped por stdin — típicamente un
`git diff` para redactar el mensaje de commit. Se detectan como un único
mensaje larguísimo sin ninguna ida y vuelta.
- **Rutas inferidas.** Un `/resume` cancelado nunca registra `cwd`, y el nombre
del directorio no se puede invertir de forma fiable (porque `/` y `.` se
codifican los dos como `-`), así que la ruta se toma prestada de otra sesión
del mismo proyecto y queda marcada.
- **Sidechains** (transcripciones de subagentes) se saltean.
- **Caché.** Lo parseado se guarda en
`$XDG_CACHE_HOME/claude-sesiones/cache.json`, indexado por tamaño y mtime. Es
solo una optimización: si falta, quedó viejo o está roto, se re-parsea todo.
`--no-cache` lo saltea por completo.
### Esquema del JSON
`--json` imprime un arreglo, de la sesión más recientemente activa a la más
vieja. Las claves son de una letra porque esos mismos registros van embebidos en
el HTML, donde el costo se paga una vez por sesión:
| Clave | Qué es |
| --- | --- |
| `id` | UUID de la sesión (el nombre del archivo). |
| `p` | Ruta del proyecto (`cwd`). |
| `b` | Rama de git. |
| `t` | Título. |
| `ai` | `true` si el título lo generó Claude. |
| `n` | `true` si parece un `claude -p` no interactivo. |
| `e` | `true` si la sesión no tiene mensajes. |
| `i` | `true` si `p` se dedujo de otra sesión del mismo proyecto. |
| `f` / `l` | Timestamp del primer y del último evento (ISO 8601). |
| `d` | Duración en minutos. |
| `u` / `a` | Cantidad de mensajes tuyos / de Claude. |
| `k` | Tamaño del archivo en KB. |
| `v` | Versión de Claude Code. |
| `c` | Transcripción: `[{"r": "u"｜"a"｜"t", "x": texto}]`. |
## Desarrollo
```bash
git clone https://github.com/ElvisClaros/claude-sesiones && cd claude-sesiones
python3 -m unittest discover -s tests -t .
```
Los tests arman árboles de `.jsonl` falsos en un directorio temporal y nunca
tocan `~/.claude`. No hay nada que instalar: ni runner de tests ni dependencias.
| Módulo | De qué se ocupa |
| --- | --- |
| `claude_sesiones/sessions.py` | Parsear los `.jsonl`, el caché, los filtros. |
| `claude_sesiones/terminal.py` | Colores ANSI, la tabla, imprimir un chat. |
| `claude_sesiones/webpage.py` | Meter los datos adentro del template. |
| `claude_sesiones/cli.py` | Los argumentos y los comandos. |
| `claude_sesiones/template.html` | La página: marcado, estilos y el código del navegador. |
## Licencia
[Apache-2.0](LICENSE).
|
