coldstart

Dos capas, una herramienta:

• El cuaderno (coldstart kb) — notas duraderas escritas por agentes sobre cómo funciona realmente este código base: para qué sirve un archivo, cómo un flujo abarca archivos, qué invariantes se mantienen. Capturadas después de tareas reales, recordadas cuando una tarea posterior coincide, y mantenidas honestas por el índice — cada nota está anclada a archivos reales, y una nota cuya evidencia se ha desviado se marca, no se sirve como verdad.
• Navegación (coldstart find / coldstart gs) — un índice estático rápido sobre rutas de archivos, nombres de símbolos, exportaciones y el grafo de importación/llamadas. Responde "¿qué archivos son relevantes para esta tarea?" en milisegundos, con evidencia comprobable en lugar de una puntuación de similitud.

Sin embeddings, sin modelo que ejecutar, sin servicio que cuidar. Los agentes ya son buenos leyendo y razonando sobre código; lo que desperdician tokens es encontrar el archivo correcto y re-derivar lo que la última sesión ya descubrió. coldstart hace esas dos partes y se aparta.

---

Instalación

Requiere Node.js 18+.

npm install -g @cstart/coldstart
cd your-project
coldstart init   # coldstart.md + client wiring + notebook + background index warm-up

Un solo coldstart init hace todo — navegación y el cuaderno. Pide dos cosas — la experiencia (cli, recomendada, o mcp) y el cliente — luego escribe la guía orientada al agente en el propio archivo de reglas del cliente (como un coldstart.md importado para Claude Code; incrustado directamente para Cursor y Codex, que no resuelven referencias @file), conecta el cliente y configura el cuaderno (esqueleto, cableado de git y — para Claude Code, Codex y Cursor — los ganchos de captura/recuerdo). Pasa --experience / --client para omitir los avisos. El cliente nunca se detecta automáticamente; siempre lo eliges tú.

• Claude Code → escribe coldstart.md y asegura que CLAUDE.md lo importe vía @coldstart.md, y registra tanto los ganchos de búsqueda find/gs (un empujón PostToolUse + un guardia PreToolUse find-dedup) como los ganchos de recuerdo/captura del cuaderno (UserPromptSubmit + Stop/SubagentStop) en .claude/settings.json — fusionados con cualquier configuración existente, nunca sobrescribiéndolos. La experiencia mcp también escribe .mcp.json.
• Codex → incrusta la guía completa de coldstart en línea en un bloque marcado en AGENTS.md (Codex no tiene inclusión @file, así que no hay un coldstart.md separado), actualizado en su lugar al re-ejecutar, y registra la navegación específica de Codex más los ganchos del cuaderno en .codex/hooks.json. El gancho de captura entiende los registros de rollout y subagente de Codex. La experiencia mcp también escribe [mcp_servers.coldstart] en .codex/config.toml.
• Cursor → escribe .cursor/rules/coldstart.mdc — una regla siempre aplicada que lleva la guía completa de coldstart en línea (Cursor no resuelve de manera confiable las referencias @file en reglas), reescrita en cada init — y registra la navegación específica de Cursor más los ganchos del cuaderno en .cursor/hooks.json (un guardia find-dedup preToolUse, un empujón postToolUse, recuerdo beforeSubmitPrompt y captura stop/subagentStop — fusionados con cualquier gancho existente). El gancho de captura analiza la transcripción de conversación propia de Cursor. La experiencia mcp también escribe .cursor/mcp.json.
• Otro → escribe solo coldstart.md e imprime las instrucciones de conexión (además de la entrada del servidor MCP para la experiencia mcp).

init luego calienta el índice en segundo plano, para que tu primera búsqueda sea instantánea. Re-ejecutar init es seguro — nunca duplica entradas.

Actualización

npm install -g @cstart/coldstart@latest
coldstart init   # re-run in each project to refresh coldstart.md

Una marca de versión en el archivo de bloqueo del keeper hace que el keeper de fondo antiguo se apague en la siguiente búsqueda; uno nuevo se genera desde el nuevo binario. No se necesita reinicio manual.

[!NOTE] Migración desde coldstart-mcp: el paquete fue renombrado coldstart-mcp → @cstart/coldstart en 2.0.0 (la CLI es ahora la superficie principal). coldstart-mcp está obsoleto pero aún se instala; cambia con npm uninstall -g coldstart-mcp && npm install -g @cstart/coldstart && coldstart init. El nombre del binario coldstart-mcp se mantiene como alias, para que las configuraciones MCP existentes sigan funcionando.

Eliminar coldstart

init escribe cableado por repositorio que un npm uninstall global no puede alcanzar (npm no dispara un gancho de desinstalación confiable, y no tiene registro de en qué repositorios hiciste init). Así que — como husky — coldstart incluye un reverso explícito:

coldstart unwire          # strip coldstart's wiring from this repo (notebook kept)
coldstart unwire --purge  # also delete .coldstart/notebook/ and its git plumbing

unwire elimina solo los marcadores propiedad de coldstart de los archivos que init tocó — entradas de gancho, la importación @coldstart.md, el bloque AGENTS.md, la entrada del servidor MCP y archivos que coldstart posee por completo (coldstart.md, .cursor/rules/coldstart.mdc) — nunca tu propio contenido en archivos compartidos. Barre los cuatro clientes, es idempotente (una segunda ejecución informa que todo ya se fue) y mantiene el cuaderno por defecto ya que son datos confirmados y compartidos. Ejecútalo en cada proyecto primero, luego npm uninstall -g @cstart/coldstart para eliminar el paquete.

---

El cuaderno

Una base de conocimiento local al repositorio escrita y leída por agentes, en .coldstart/notebook/:

coldstart kb search tile save lifecycle   # plain task words, symbols, or file names
coldstart kb lookup src/models.py Tile    # everything known at one exact address
coldstart kb write spec.json              # the write gate (two-phase dedup)
coldstart kb commit                       # publish notes to git, nothing else rides along
coldstart kb view                         # open a single-file HTML browser of the notebook
coldstart kb repair                       # worklist of notes that are written but unfindable
coldstart kb repair-aliases                # worklist of aliases that may no longer be true
coldstart kb status / lint / render / init / migrate

Qué es una nota. Tres formas: una nota de archivo (para qué sirve un archivo — un resumen único, o facetas por símbolo para archivos centrales), una nota de flujo (una historia entre archivos: pasos ordenados, invariantes) y una lección (una trampa, regla, causa de error, razón o ausencia confirmada). Cada nota lleva anclas — rutas de archivo y símbolos concretos en los que se apoyan sus afirmaciones.

Dónde llegan las notas al agente. Tres superficies, sin nuevos hábitos requeridos:

1. Líneas Summary: en resultados de find — una visión general verificada de un archivo por un agente anterior, justo donde el archivo se clasifica. [fresh] significa que el archivo es idéntico byte a byte a cuando se verificó el resumen — el agente puede confiar en él sin volver a leer el archivo.
2. Recuerdo al momento del aviso (gancho opcional) — las notas cuyos títulos, alias o anclas coinciden con el aviso entrante se muestran como un bloque compacto de título + idea + ruta, con límite máximo, enmarcado como datos de referencia. Nada coincide → nada se inyecta.
3. kb search / kb lookup — un motor de búsqueda sobre el cuaderno para cambios de vocabulario a mitad de tarea, y una búsqueda de dirección exacta (path [symbol]) antes de editar un archivo.

Por qué se puede confiar. Esta es la parte que requirió el trabajo de diseño:

• La frescura es mecánica, no esperada. Cada ancla se sella con un hash de contenido al momento de escribir; el índice vuelve a verificar los sellos a medida que el código cambia. Una nota desviada se muestra [evidence changed: <path>] y la guía dice re-verificar — el conocimiento obsoleto se degrada a una hipótesis etiquetada en lugar de una mentira confiada.
• El registro es la verdad. Las notas viven en un registro de eventos .raw de solo añadir (haz commit — las fusiones son uniones, así que las ramas paralelas de notas se reconcilian sin conflictos). Las notas Markdown se derivan, se regeneran mecánicamente y se ignoran en git.
• Las escrituras pasan por una puerta. El concepto de una nueva nota se busca primero contra las notas existentes — el agente debe fusionarse explícitamente en una coincidencia (--into <id>) o declararla nueva (--new). Los duplicados se controlan al momento de escribir, no se limpian después.
• Las sesiones concurrentes son seguras. Múltiples agentes pueden escribir a la vez: registros de solo añadir por nota, creación exclusiva para nuevos IDs de nota (un duplicado en el mismo momento se convierte en dos notas visibles, nunca una fusión silenciosa), fusión sin pérdida para notas de archivo compartidas y renderizados atómicos (un lector nunca ve una nota a medio escribir).
• Las correcciones ocurren en la sesión. Si un agente encuentra una nota incorrecta mientras la evidencia está en su contexto, la guía le dice que corrija o retire la nota en ese momento — no existe un agente futuro mejor ubicado.

Configuración: el cuaderno viene con coldstart init — sin paso separado. Crea el esqueleto del cuaderno, establece la fusión de unión para los registros y (en Claude Code, Codex y Cursor) conecta los dos ganchos — captura al final de la sesión, recuerdo al momento del aviso. (coldstart kb init todavía existe como alias si quieres (re-)conectar solo el cuaderno.) Otros hosts pueden manejar el cuaderno sin los ganchos: a través de la CLI completa kb, o — para clientes sin shell — las herramientas MCP kb_search / kb_lookup / kb_write / kb_status / kb_repair / kb_repair_aliases.

Independiente del lenguaje. La maquinaria de frescura del cuaderno se basa en hash de contenido, por lo que funciona en cualquier código base — incluidos lenguajes que el índice de navegación no analiza. Donde el índice sí analiza, las notas adicionalmente obtienen frescura a nivel de símbolo.

[!NOTE] El cuaderno es joven. Lo que está verificado hoy: notas escritas por agentes en sesiones reales resultaron precisas contra el código; el ciclo de nota obsoleta se cierra de extremo a extremo (marcar → re-leer → corregir); la captura, el recuerdo y las escrituras concurrentes resisten bajo estrés. La apuesta — declarada como apuesta — es que un corpus como este se acumula durante la vida del repositorio: la segunda vez que surge cualquier pregunta, la respuesta está a un Read de distancia en lugar de una re-derivación.

---

Navegación: las dos operaciones

	Qué responde	Reemplaza
find <terms>	"¿Qué archivos tratan sobre esto?" — clasifica archivos por cuántos de tus términos de consulta cubren (nombres de archivo, segmentos de ruta, símbolos exportados, más un pase de referencia de nombres en todo el repositorio).	una ráfaga de grep/glob mientras te orientas
gs <file>	"¿Qué es este archivo?" — símbolos de nivel superior con rangos de línea, quién lo importa, quién llama a cada símbolo y vecinos relacionados por nombre.	leer un archivo completo solo para aprender su forma y uso

El flujo previsto: find un concepto → elige la mejor ruta → gs ese archivo para su forma y quién lo usa → Read solo para la implementación dentro del cuerpo de un método. Los resúmenes del cuaderno viajan junto con los resultados de find, así que a menudo el paso de orientación se responde solo.

flowchart LR
    A["coldstart find<br/>which files?"] --> B["coldstart gs<br/>what is it? who uses it?"] --> C["Read<br/>just the method body"]
    class A,B cold
    class C warm
    classDef cold stroke:#16708f,stroke-width:2px
    classDef warm stroke:#c26714,stroke-width:2px

find — localiza los archivos para un concepto

coldstart find auth session cookie

[!TIP] Pasa cada identificador relevante de tu tarea — el símbolo, el sustantivo del dominio, el token raro que recuerdas a medias — no una palabra clave destilada. find clasifica archivos por cuántos de tus términos cubre cada uno y muestra, por archivo, qué términos define vs. importa y una vista previa de las líneas donde se agrupan. A menudo eso es suficiente para responder sin abrir nada.

En cuanto a velocidad, find compite con grep crudo: su pase de referencia en todo el repositorio se ejecuta en ripgrep — el tuyo desde PATH, la copia incluida o la de un editor (COLDSTART_RG anula) — con respaldos git grep/grep, y la página clasificada proviene del índice preconstruido, no de un escaneo. Banderas: --path GLOB (alcance; combinar con comas, ! excluye) · --tests (incluir archivos de prueba) · --via (mostrar relaciones de referencias por nombre) · --json

gs — profundizar en un archivo

coldstart gs src/auth/service.ts

Devuelve los símbolos del archivo (con rangos de línea), sus importaciones internas de 1 salto, quién lo importa y los llamadores entre archivos por símbolo — en una sola llamada. Esta es la respuesta a "quién usa este archivo / quién llama a este símbolo"; no es un grep.

Banderas: --symbol a,b (entregar cuerpos de métodos nombrados en línea) · --match TERM (filtrar un archivo gigante a una sola área; a|b = OR, /regex/ = regex) · --view symbols|imports|importers|callers · --json

Consultas independientes por lotes en una sola llamada de shell

coldstart find auth; coldstart find 'session cookie'; coldstart gs src/auth/service.ts

---

Dos formas de llamarlo, salida idéntica

coldstart se distribuye como un solo binario con dos puertas de entrada:

• CLI (principal) — coldstart find … / coldstart gs … / coldstart kb …. Para cualquier agente capaz de usar shell (Claude Code, Cursor, uso en terminal). Este es el camino rápido.
• MCP (para clientes sin shell) — las herramientas find y gs, además del cuaderno como kb_search / kb_lookup / kb_write / kb_status / kb_repair / kb_repair_aliases, todo byte-idéntico al CLI. Para clientes como Claude Desktop que no tienen shell. (kb commit sigue siendo solo CLI/humano — publicar notas en git nunca es una acción de agente.)

Mismo motor, mismo índice, mismos resultados. Elige el que tu agente pueda alcanzar.

Funciona mejor con Claude Code, Codex y Cursor: los tres reciben hooks específicos de plataforma para find/gs y hooks de captura/recuperación del cuaderno desde coldstart init. Cualquier otro cliente recibe coldstart.md más instrucciones impresas de conexión.

---

Trae tu propia semántica

coldstart no tiene embeddings, ni resúmenes generados, ni capa semántica calculada en tiempo de indexación — a propósito. La capa semántica es el agente. Cada consumidor ya es un modelo de frontera; precomputar significado en tiempo de indexación solo lo duplica, peor y obsoleto. Así que el índice conserva lo que es barato mantener exacto — rutas, símbolos, exportaciones, el grafo de importación/llamadas — y devuelve por qué cada archivo fue clasificado.

El cuaderno es la misma filosofía aplicada a la memoria: coldstart tampoco calcula significado propio. Almacena, ancla y verifica la frescura del significado que los agentes redactan — escrito en el momento de la tarea, por el razonador que tenía el contexto completo, sobre la pregunta que realmente importaba. El argumento completo está en PHILOSOPHY.md.

---

Cómo se mantiene fresco el índice

coldstart es un guardián, lectores delgados:

flowchart TD
    K["keeper — coldstart --daemon<br/>watches repo, patches/rebuilds, saves cache<br/>serves nothing"] -->|debounced save| C[("on-disk cache")]
    C --> F["coldstart find<br/>reads cache, prints"]
    C --> G["coldstart gs<br/>reads cache, prints"]
    C --> M["MCP server<br/>reads cache, stdio"]
    class K cold
    classDef cold stroke:#16708f,stroke-width:2px

• Un único proceso guardián por repositorio vigila el sistema de archivos y mantiene actualizado el caché en disco. No responde consultas.
• Los lectores CLI (find/gs) y el servidor MCP son lectores sin estado sobre ese caché. El primer lector de un repositorio lanza perezosamente al guardián, así que incluso las ediciones sin confirmar permanecen activas.
• Los lectores nunca construyen el índice. Ante una falta de caché, esperan la construcción del guardián (progreso en stderr) en lugar de lanzar silenciosamente una construcción de varios minutos en línea — o tres de ellas en concurrente.
• Sin HTTP, sin puertos, sin puente. El guardián registra en ~/.coldstart/daemon/<root>.log y sale cuando se elimina su archivo de bloqueo.

No hay TTL de caché. El índice nunca se descarta por ser viejo — se mantiene correcto en su lugar:

• Mientras el guardián corre: las ediciones se debouncean (400 ms), luego se parchean incrementalmente (~2–5 ms/archivo, hasta 30 archivos o el 20% del repositorio, lo que sea mayor) o se dispara una reconstrucción completa en segundo plano por encima de eso (servida desde el último índice bueno hasta el intercambio). El caché se re-guarda ~5 s después de que las ediciones se asientan, en generaciones atómicas — un lector nunca puede cargar una mezcla a medio escribir de viejo y nuevo.
• Cuando el guardián arranca: reconcilia — verifica por stat cada archivo indexado contra su huella almacenada (~150 ms incluso con 16k archivos) más un diff de git contra el HEAD indexado — y parchea exactamente lo que cambió mientras nada vigilaba. Un cambio de rama que solía forzar una reconstrucción de 96 segundos en un repositorio de 16k archivos ahora es un parche de ~3 segundos.
• Como red de seguridad: cada parche se verifica con lint contra los invariantes del índice (una violación dispara una reconstrucción automática y aterriza en un registro de reparación que status muestra), y una auditoría rotativa de huellas después de cada guardado detecta eventos que el vigilante perdió.

El guardián también sella la frescura de los anclajes del cuaderno (un sidecar pequeño, derivado single-flight) — el cuaderno nunca carga el índice de código para responder una consulta.

Comandos de ciclo de vida

coldstart status              # keepers on this machine: alive? fresh? last patch/rebuild/save? repairs?
coldstart restart             # kill the current repo's keeper (respawns on next lookup)
coldstart restart --root DIR  # kill a specific repo's keeper from anywhere
coldstart restart --all       # kill every keeper
coldstart index               # build + save the cache once, up front (single-writer prep)

restart es la jugada correcta siempre que algo se sienta obsoleto — un guardián nuevo reconcilia al arrancar, así que vuelve correcto, no solo vivo. status responde "¿está fresco mi índice, y por qué?": vivacidad, antigüedad del caché, los sellos del último reconcile/parche/reconstrucción/guardado del guardián, y la cola del registro de reparación — sin sonda de red.

---

Lenguajes soportados

Índice de navegación: TypeScript, JavaScript, JSX/TSX, Vue, Svelte, Astro, AngularJS 1.x, Java, Kotlin, Ruby (consciente de Rails: asociaciones has_many/belongs_to, recursos routes.rb, aristas controlador↔vista), Python (aristas de convención Django), Go, Rust, C#, PHP (aristas de convención Laravel), C++, Groovy (incl. DSL de Gradle), GraphQL, YAML, TOML, XML y archivos .env.

No indexados: Swift, Dart — sin mapeo de extensión; estos archivos no se recorren ni se analizan.

El cuaderno funciona independientemente — sus sellos de frescura se basan en hash de contenido, así que las notas sobre un repositorio Swift son tan confiables como las notas sobre uno de TypeScript (solo les falta el detalle de frescura a nivel de símbolo).

---

Cuándo no recurrir a él

• Una cadena literal / frase / regex dentro de los cuerpos de archivo → Grep.
• Leer una implementación → Read, después de que gs te dé la forma.
• find dice "ningún archivo indexado contiene alguno de […]" → esos identificadores no están en el repositorio. No hagas grep de variantes ortográficas.

---

Desarrollo

npm install
npm run build
npm test

# run a query from your build:
node dist/index.js find auth --root .

# run the MCP server in a single process (no background keeper) for debugging:
node dist/index.js --root . --no-daemon

Consulta PHILOSOPHY.md para saber por qué coldstart no calcula semántica propia, ARCHITECTURE.md para el pipeline del índice, el modelo de procesos y los internals del cuaderno, y TROUBLESHOOTING.md para los procedimientos de recuperación.

---

Limitaciones

1. Es una capa de enrutamiento más un cuaderno escrito por agentes — sin análisis semántico ni resúmenes de código generados. Esto es deliberado: el agente consumidor es la capa semántica (ver PHILOSOPHY.md).
2. Los llamadores de gs son de un salto y con alcance de archivo. Las llamadas de expresión de miembro (this.method(), api.method()) no se resuelven entre archivos; las llamadas a funciones/constantes nombradas sí. Persigue más saltos llamando a gs en los archivos llamadores.
3. Las importaciones dinámicas/computadas (import(variable)) y las referencias DSL en tiempo de ejecución (asociaciones polimórficas, modelos respaldados por gem/reflexión) permanecen sin resolver.
4. Los directorios ocultos y los archivos de más de 1 MB se omiten en el índice.
5. El guardián es por repositorio y por máquina — sin compartir entre proyectos o hosts. El cuaderno sí viaja: sus registros .raw se confirman y se fusionan por unión entre ramas y máquinas.
6. La calidad del cuaderno está limitada por lo que los agentes que escriben realmente leen — las notas son precisas sobre lo que declaran, pero una nota no es una prueba de completitud.

Escritura

Piezas más largas sobre los problemas detrás de esta herramienta — qué cuestan realmente las sesiones de agentes, y qué le pasó al diseño cuando las mediciones discreparon del plan.

• A dónde van los tokens en una sesión de agente — el costo de la sesión es aproximadamente turnos × contexto residente, y la salida es un error de redondeo. Cómo descomponer tus propias transcripciones en lugar de confiar en los números publicados por cualquiera.
• Un índice no puede responder la misma pregunta dos veces — un grafo de código hace cada salto más barato sin reducir cuántos saltos das, y clasificar por grado de entrada hace que los archivos hoja sean estructuralmente inclasificables.
• La herramienta que el agente no llama — disponibilidad, documentación e instrucción explícita aún no suman adopción. Incluyendo las veces que nuestros propios agentes evitaron nuestro propio comando.
• De cuatro herramientas a dos — qué herramientas se eliminaron, qué capacidad se fue genuinamente con ellas, y por qué la superficie se mantuvo pequeña después.
• Las notas sobre código deberían escribirlas quienes leyeron el código — por qué el cuaderno captura en sesión en lugar de resumir transcripciones después.

Licencia

MIT — ver LICENSE.

---