coldstart

Duas camadas, uma ferramenta:

• O caderno (coldstart kb) — notas duráveis, escritas por agentes, sobre como este código-fonte realmente funciona: para que serve um arquivo, como um fluxo atravessa arquivos, quais invariantes se mantêm. Capturadas após tarefas reais, recuperadas quando uma tarefa posterior corresponde e mantidas honestas pelo índice — cada nota está ancorada a arquivos reais, e uma nota cuja evidência se desatualizou é sinalizada, não servida como verdade.
• Navegação (coldstart find / coldstart gs) — um índice estático rápido sobre caminhos de arquivos, nomes de símbolos, exportações e o grafo de importações/chamadas. Ele responde "quais arquivos são relevantes para esta tarefa?" em milissegundos, com evidência verificável em vez de uma pontuação de similaridade.

Sem embeddings, sem modelo para executar, sem serviço para cuidar. Agentes já são bons em ler e raciocinar sobre código; o que eles desperdiçam em tokens é encontrar o arquivo certo e re-derivar o que a última sessão já descobriu. O coldstart faz essas duas partes e sai do caminho.

---

Instalação

Requer Node.js 18+.

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

Um único coldstart init faz tudo — navegação e o caderno. Ele pede duas coisas — a experiência (cli, recomendada, ou mcp) e o cliente — e então escreve a orientação voltada ao agente no próprio arquivo de regras do cliente (como um coldstart.md importado para Claude Code; embutido diretamente para Cursor e Codex, que não resolvem referências @file), conecta o cliente e configura o caderno (esqueleto, integração com git e — para Claude Code, Codex e Cursor — os ganchos de captura/recuperação). Passe --experience / --client para pular os prompts. O cliente nunca é detectado automaticamente; você sempre o escolhe.

• Claude Code → escreve coldstart.md e garante que CLAUDE.md o importe via @coldstart.md, e registra tanto os ganchos de busca find/gs (um lembrete PostToolUse + uma proteção de deduplicação find PreToolUse) quanto os ganchos de recuperação/captura do caderno (UserPromptSubmit + Stop/SubagentStop) em .claude/settings.json — mesclados em quaisquer configurações existentes, nunca sobrescrevendo-as. A experiência mcp também escreve .mcp.json.
• Codex → embute a orientação completa do coldstart inline em um bloco marcado em AGENTS.md (Codex não tem include @file, então não há um coldstart.md separado), atualizado no lugar em re-execuções, e registra ganchos de navegação e caderno específicos do Codex em .codex/hooks.json. O gancho de captura entende transcrições de rollout e subagentes do Codex. A experiência mcp também escreve [mcp_servers.coldstart] em .codex/config.toml.
• Cursor → escreve .cursor/rules/coldstart.mdc — uma regra sempre aplicada que carrega a orientação completa do coldstart inline (Cursor não resolve referências @file em regras de forma confiável), reescrita a cada init — e registra ganchos de navegação e caderno específicos do Cursor em .cursor/hooks.json (uma proteção de deduplicação find preToolUse, um lembrete postToolUse, recuperação beforeSubmitPrompt e captura stop/subagentStop — mesclados em quaisquer ganchos existentes). O gancho de captura analisa a transcrição de conversa do próprio Cursor. A experiência mcp também escreve .cursor/mcp.json.
• Outros → escreve apenas coldstart.md e imprime as instruções de conexão (além da entrada do servidor MCP para a experiência mcp).

Em todos os clientes, o gancho PostToolUse também entrega o sinal "Editados juntos" sem esperar ser solicitado. Uma vez que um agente editou dois arquivos diferentes, ele nomeia os arquivos que o histórico do git diz que continuam mudando junto com eles — a implementação irmã, o teste em outra linguagem, a documentação que se desatualiza. Agentes não executam gs de forma confiável antes de editar, então o sinal só os alcançava se eles fossem procurar; isso o coloca diante deles no momento da edição. É consultivo: a mensagem diz claramente que a relação é um hábito, não uma dependência de código, e pede ao agente para verificar em vez de mudar qualquer coisa. Cada arquivo é nomeado no máximo uma vez por tarefa, e a lista é redefinida sempre que você envia uma nova mensagem.

init então aquece o índice em segundo plano, para que sua primeira consulta seja instantânea. Re-executar init é seguro — nunca duplica entradas.

Atualização

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

Um carimbo de versão no lockfile do keeper faz o keeper antigo em segundo plano desligar na próxima consulta; um novo é gerado a partir do novo binário. Sem reinicialização manual necessária.

[!NOTE] Migrando do coldstart-mcp: o pacote foi renomeado coldstart-mcp → @cstart/coldstart na versão 2.0.0 (a CLI agora é a superfície principal). coldstart-mcp está obsoleto, mas ainda instala; mude com npm uninstall -g coldstart-mcp && npm install -g @cstart/coldstart && coldstart init. O nome do binário coldstart-mcp é mantido como alias, então configurações MCP existentes continuam funcionando.

Removendo o coldstart

init escreve configuração por repositório que um npm uninstall global não consegue alcançar (o npm não dispara um gancho de desinstalação confiável e não tem registro de quais repositórios você init'd). Então — como o husky — o coldstart inclui um 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 remove apenas marcadores de propriedade do coldstart dos arquivos que init tocou — entradas de gancho, a importação @coldstart.md, o bloco AGENTS.md, a entrada do servidor MCP e arquivos totalmente de propriedade do coldstart (coldstart.md, .cursor/rules/coldstart.mdc) — nunca seu próprio conteúdo em arquivos compartilhados. Ele varre todos os quatro clientes, é idempotente (uma segunda execução relata que tudo já foi removido) e mantém o caderno por padrão, já que é um dado commitado e compartilhado. Execute-o em cada projeto primeiro, depois npm uninstall -g @cstart/coldstart para remover o pacote.

---

O caderno

Uma base de conhecimento local ao repositório, escrita e lida por agentes, em .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

O que é uma nota. Três formatos: uma nota de arquivo (para que serve um arquivo — um resumo único ou facetas por símbolo para arquivos centrais), uma nota de fluxo (uma história entre arquivos: etapas ordenadas, invariantes) e uma lição (uma armadilha, regra, causa de bug, justificativa ou ausência confirmada). Cada nota carrega âncoras — caminhos de arquivo e símbolos concretos nos quais suas afirmações se apoiam.

Onde as notas alcançam o agente. Três superfícies, sem novos hábitos necessários:

1. Linhas Summary: nos resultados de find — uma visão geral verificada de um arquivo por um agente anterior, exatamente onde o arquivo é classificado. [fresh] significa que o arquivo é byte-idêntico ao momento em que o resumo foi verificado — o agente pode confiar nele sem reler o arquivo.
2. Recuperação no momento do prompt (gancho opcional) — notas cujos títulos, aliases ou âncoras correspondem ao prompt recebido são exibidas como um bloco compacto de título + essência + caminho, com limite rígido, enquadrado como dados de referência. Nada corresponde → nada é injetado.
3. kb search / kb lookup — um mecanismo de busca sobre o caderno para mudanças de vocabulário no meio da tarefa, e uma consulta de endereço exato (path [symbol]) antes de editar um arquivo.

Por que pode ser confiável. Esta é a parte que exigiu o trabalho de design:

• Atualidade é mecânica, não esperada. Cada âncora é carimbada com um hash de conteúdo no momento da escrita; o índice re-verifica os carimbos conforme o código muda. Uma nota desatualizada renderiza [evidence changed: <path>] e a orientação diz para re-verificar — conhecimento obsoleto degrada em uma hipótese rotulada em vez de uma mentira confiante.
• O log é a verdade. As notas vivem em um log de eventos .raw somente-acréscimo (faça commit dele — merges são uniões, então ramos paralelos de notas se reconciliam sem conflitos). As notas Markdown são derivadas, regeneradas mecanicamente e ignoradas pelo git.
• Escritas passam por uma barreira. O conceito de uma nova nota é primeiro buscado contra notas existentes — o agente deve mesclar explicitamente em uma correspondência (--into <id>) ou declará-la nova (--new). Duplicatas são barradas no momento da escrita, não limpas depois.
• Sessões concorrentes são seguras. Vários agentes podem escrever ao mesmo tempo: logs somente-acréscimo por nota, criação exclusiva para novos IDs de nota (uma duplicata no mesmo instante vira duas notas visíveis, nunca uma mesclagem silenciosa), mesclagem sem perdas para notas de arquivo compartilhadas e renderizações atômicas (um leitor nunca vê uma nota pela metade).
• Correções acontecem na sessão. Se um agente encontrar uma nota errada enquanto a evidência está em seu contexto, a orientação diz para corrigir ou retratar a nota naquele momento — não existe agente futuro melhor posicionado.

Configuração: o caderno vem com coldstart init — sem etapa separada. Ele cria o esqueleto do caderno, define merge-união para os logs e (no Claude Code, Codex e Cursor) conecta os dois ganchos — captura no fim da sessão, recuperação no momento do prompt. (coldstart kb init ainda existe como alias se você quiser (re)conectar apenas o caderno.) Outros hosts podem dirigir o caderno sem os ganchos: via a CLI completa kb ou — para clientes sem shell — as ferramentas MCP kb_search / kb_lookup / kb_write / kb_status / kb_repair / kb_repair_aliases.

Agnóstico a linguagem. A maquinaria de atualidade do caderno é baseada em hash de conteúdo, então funciona em qualquer código-fonte — incluindo linguagens que o índice de navegação não analisa. Onde o índice analisa, as notas adicionalmente ganham atualidade em nível de símbolo.

[!NOTE] O caderno é jovem. O que está verificado hoje: notas escritas por agentes em sessões reais conferidas como precisas contra o código; o ciclo de nota desatualizada fecha de ponta a ponta (sinalizar → reler → correção); captura, recuperação e escritas concorrentes se sustentam sob estresse. A aposta — declarada como aposta — é que um corpus assim se acumula ao longo da vida de um repositório: na segunda vez que qualquer pergunta surgir, a resposta está a um Read de distância em vez de uma re-derivação.

---

Navegação: as duas operações

	O que responde	Substitui
find <terms>	"Quais arquivos são sobre isto?" — classifica arquivos por quantos dos seus termos de consulta eles cobrem (nomes de arquivo, segmentos de caminho, símbolos exportados, além de uma passada de referência de nomes em todo o repositório).	uma enxurrada de grep/glob durante a orientação
gs <file>	"O que é este arquivo?" — símbolos de nível superior com intervalos de linha, quem o importa, quem chama cada símbolo e vizinhos relacionados por nome.	ler um arquivo inteiro só para aprender sua forma e uso

O fluxo pretendido: find um conceito → escolha o melhor caminho → gs esse arquivo para sua forma e quem o usa → Read apenas para a implementação dentro do corpo de um método. Resumos do caderno acompanham os resultados de find, então muitas vezes a etapa de orientação se responde sozinha.

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 — localize os arquivos para um conceito

coldstart find auth session cookie

[!TIP] Passe cada identificador saliente da sua tarefa — o símbolo, o substantivo de domínio, o token raro que você lembra vagamente — não apenas uma palavra-chave destilada. find classifica arquivos por quantos dos seus termos cada um cobre e mostra, por arquivo, quais termos ele define vs. importa, além de uma prévia das linhas onde eles se agrupam. Muitas vezes isso é suficiente para responder sem abrir nada.

Em termos de velocidade, find compete com grep puro: sua passagem de referência em todo o repositório roda em ripgrep — o seu do PATH, a cópia embutida, ou a de um editor (COLDSTART_RG substitui) — com fallbacks de git grep/grep, e a página classificada vem do índice pré-construído, não de uma varredura.

Flags: --path GLOB (escopo; combine com vírgulas, ! exclui) · --tests (incluir arquivos de teste) · --via (mostrar relações de referência de nome) · --json

gs — aprofunde-se em um arquivo

coldstart gs src/auth/service.ts

Retorna os símbolos do arquivo (com intervalos de linha), seus imports internos de 1 salto, quem o importa e chamadores entre arquivos por símbolo — em uma única chamada. Esta é a resposta para "quem usa este arquivo / quem chama este símbolo"; não é um grep.

Flags: --symbol a,b (entregar corpos de métodos nomeados inline) · --match TERM (filtrar um god-file para uma área; a|b = OR, /regex/ = regex) · --view symbols|imports|importers|callers · --json

graph — veja o repositório inteiro de uma vez

coldstart graph

Para humanos, não para agentes. Escreve um único arquivo HTML autocontido e o abre: cada arquivo indexado é um ponto em uma esfera, posicionado por diretório, e clicar em um abre uma visão 2D de tudo ao qual ele está conectado — com cada relação nomeada (imports, calls save(), load(), edited together · 13 of 42 commits, same note · <title>). Clique em um vizinho para abrir suas conexões; clique em um deles e a visão desliza, então você sempre vê dois níveis em vez de uma bola de fios em crescimento.

Sem dependências. A página é HTML, CSS e um script de canvas com os dados do seu repositório embutidos — sem servidor, sem etapa de build, e nada sai da sua máquina. Envie por e-mail, coloque em um gist, abra em um avião. Experimente no próprio código do coldstart.

Flags: --out PATH (padrão .coldstart/graph.html, gitignored para você) · --no-open · --json

Agrupe buscas independentes em uma única chamada de shell

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

---

Duas maneiras de chamar, saída idêntica

coldstart vem como um único binário com duas portas de entrada:

• CLI (principal) — coldstart find … / coldstart gs … / coldstart kb …. Para qualquer agente com shell (Claude Code, Cursor, uso em terminal). Este é o caminho rápido.
• MCP (para clientes sem shell) — as ferramentas find e gs, além do notebook como kb_search / kb_lookup / kb_write / kb_status / kb_repair / kb_repair_aliases, todas byte-idênticas ao CLI. Para clientes como Claude Desktop que não têm shell. (kb commit permanece apenas CLI/humano — publicar notas no git nunca é uma ação de agente.)

Mesmo motor, mesmo índice, mesmos resultados. Escolha o que seu agente conseguir alcançar.

Funciona melhor com Claude Code, Codex e Cursor: todos os três recebem hooks específicos de plataforma para find/gs e hooks de captura/recuperação de notebook do coldstart init. Qualquer outro cliente recebe coldstart.md além de instruções impressas de conexão.

---

Traga sua própria semântica

coldstart não tem embeddings, resumos gerados ou camada semântica calculada no momento da indexação — de propósito. A camada semântica é o agente. Todo consumidor já é um modelo de fronteira; pré-computar significado no momento da indexação apenas duplica isso, pior e desatualizado. Então o índice mantém o que é barato manter exato — caminhos, símbolos, exports, o grafo de import/chamada — e retorna por que cada arquivo foi classificado.

O notebook é a mesma filosofia aplicada à memória: coldstart ainda não calcula significado próprio. Ele armazena, ancora e verifica a frescor do significado que agentes criam — escrito no momento da tarefa, pelo raciocinador que tinha o contexto completo, sobre a pergunta que realmente importava. O argumento completo está em PHILOSOPHY.md.

---

Como o índice se mantém atualizado

coldstart é um keeper, leitores finos:

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

• Um único processo keeper por repositório observa o sistema de arquivos e mantém o cache em disco atualizado. Ele não responde consultas.
• Os leitores CLI (find/gs) e o servidor MCP são leitores sem estado sobre esse cache. O primeiro leitor de um repositório inicia o keeper de forma lazy, então até edições não commitadas permanecem ativas.
• Leitores nunca constroem o índice. Em uma falha de cache, eles esperam a construção do keeper (progresso no stderr) em vez de iniciar silenciosamente uma construção de vários minutos inline — ou três delas concorrentemente.
• Sem HTTP, sem portas, sem ponte. O keeper registra logs em ~/.coldstart/daemon/<root>.log e sai quando seu arquivo de lock é removido.

Não há TTL de cache. O índice nunca é descartado por ser antigo — ele é mantido correto em vez disso:

• Enquanto o keeper roda: edições são debounced (400 ms), então aplicadas incrementalmente (~2–5 ms/arquivo, até 30 arquivos ou 20% do repositório, o que for maior) ou disparam uma reconstrução completa em segundo plano acima disso (servida do último índice bom até a troca). O cache é re-salvo ~5 s após as edições se estabilizarem, em gerações atômicas — um leitor nunca pode carregar uma mistura meio escrita de antigo e novo.
• Quando o keeper inicia: ele reconcilia — verifica estatísticas de cada arquivo indexado contra sua impressão digital armazenada (~150 ms mesmo com 16k arquivos) além de um diff git contra o HEAD indexado — e aplica exatamente o que mudou enquanto nada estava observando. Uma troca de branch que costumava forçar uma reconstrução de 96 segundos em um repositório de 16k arquivos agora é um patch de ~3 segundos.
• Como rede de segurança: cada patch é verificado com lint contra invariantes do índice (uma violação dispara uma reconstrução automática e cai em um log de reparo que status mostra), e uma auditoria rotativa de impressões digitais após cada salvamento captura eventos perdidos pelo watcher.

O keeper também carimba a frescor das âncoras do notebook (um sidecar pequeno, derivado single-flight) — o notebook nunca carrega o índice de código para responder uma 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 é a jogada certa sempre que algo parecer desatualizado — um keeper novo reconcilia no início, então ele volta correto, não apenas vivo. status responde "meu índice está atualizado, e por quê?": liveness, idade do cache, carimbos do último reconcile/patch/rebuild/save do keeper e o final do log de reparo — sem sonda de rede.

---

Linguagens suportadas

Índice de navegação: TypeScript, JavaScript, JSX/TSX, Vue, Svelte, Astro, AngularJS 1.x, Java, Kotlin, Ruby (ciente de Rails: associações has_many/belongs_to, recursos routes.rb, arestas controller↔view), Python (arestas de convenção Django), Go, Rust, C#, PHP (arestas de convenção Laravel), C++, Groovy (incl. DSL Gradle), GraphQL, YAML, TOML, XML e arquivos .env.

Não indexados: Swift, Dart — sem mapeamento de extensão; esses arquivos não são percorridos nem analisados.

O notebook funciona independentemente — seus carimbos de frescor são baseados em hash de conteúdo, então notas em um repositório Swift são tão confiáveis quanto notas em um TypeScript (apenas sem detalhes de frescor em nível de símbolo).

---

Quando não usar

• Uma string literal / frase / regex dentro de corpos de arquivo → Grep.
• Ler uma implementação → Read, depois que gs te der a forma.
• find diz "nenhum arquivo indexado contém qualquer um de […]" → esses identificadores não estão no repositório. Não faça grep de variações de grafia.

---

Desenvolvimento

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

Veja PHILOSOPHY.md para saber por que coldstart não calcula semântica própria, ARCHITECTURE.md para o pipeline do índice, modelo de processo e internals do notebook, e TROUBLESHOOTING.md para procedimentos de recuperação.

---

Limitações

1. É uma camada de roteamento mais um notebook escrito por agente — sem análise semântica ou resumos de código gerados. Isso é deliberado: o agente consumidor é a camada semântica (veja PHILOSOPHY.md).
2. Chamadores gs são de um salto e com escopo de arquivo. Chamadas de expressão de membro (this.method(), api.method()) não são resolvidas entre arquivos; chamadas de função/constante nomeada são. Persiga mais saltos chamando gs nos arquivos chamadores.
3. Imports dinâmicos/computados (import(variable)) e referências de DSL em runtime (associações polimórficas, modelos baseados em gem/reflexão) permanecem não resolvidos.
4. Diretórios ocultos e arquivos acima de 1 MB são ignorados pelo índice.
5. O keeper é por repositório e por máquina — sem compartilhamento entre projetos ou hosts. O notebook viaja: seus logs .raw são commitados e fazem merge de união entre branches e máquinas.
6. A qualidade do notebook é limitada pelo que os agentes escritores realmente leem — notas são precisas sobre o que afirmam, mas uma nota não é prova de completude.

Medido

Dois repositórios, cada um executado mais de uma vez, com o CLI. Cada pergunta é feita em dois braços que diferem apenas se coldstart está instalado: a linha de base é Claude Code puro usando as ferramentas de busca que ele traz. Sonnet 5 em ambos os lados, uma sessão nova por pergunta.

Repositório	Linguagem	Tokens vs. linha de base	Recall	Perguntas
Arches	Python / Django	−64%	+2 pts	27
JMRI	Java	−31%	paridade	25

As perguntas vêm de relatórios de issues fechados, que são escritos antes de alguém saber onde o defeito mora, então descrevem um sintoma em vez de nomear um arquivo. A resposta correta é o conjunto de arquivos de origem no commit que fechou a issue, então a verdade básica vem do histórico do git, não do julgamento de ninguém.

Esses dois números não são calculados em média. O custo por turno difere por linguagem, e a economia vem de remover turnos, então uma pergunta que um agente resolve em dois ou três turnos tem pouco a devolver. Um benchmark anterior em Kafka, Django e Mastodon foi descartado: o modelo leu todos os três, e isso contaminou ambos os braços. O método completo, incluindo o que foi descartado e por quê, está em coldstartmcp.dev/benchmark. O harness em si é um projeto separado, coldbench, e funciona em qualquer repositório com histórico git, incluindo privados. Ambos os conjuntos de perguntas são publicados com suas listas de arquivos dourados e o número da issue por trás de cada pergunta, em coldbench/examples.

Escrita

Pedaços mais longos sobre os problemas por trás desta ferramenta — o que sessões de agente realmente custam, e o que aconteceu ao design quando as medições discordaram do plano.

• Onde os tokens vão em uma sessão de agente — o custo da sessão é aproximadamente turnos × contexto residente, e a saída é um erro de arredondamento. Como decompor seus próprios transcripts em vez de confiar nos números publicados de alguém.
• Um índice não pode responder à mesma pergunta duas vezes — um grafo de código torna cada salto mais barato sem reduzir quantos saltos você dá, e classificar por in-degree torna arquivos folha estruturalmente não classificáveis.
• A ferramenta que o agente não chama — disponibilidade, documentação e uma instrução explícita ainda não somam adoção. Incluindo as vezes em que nossos próprios agentes ignoraram nosso próprio comando.
• De quatro ferramentas para duas — quais ferramentas foram deletadas, qual capacidade genuinamente foi junto, e por que a superfície permaneceu pequena depois.
• Notas sobre código devem ser escritas por quem leu o código — por que o notebook captura em sessão em vez de resumir transcripts depois.

Licença

MIT — veja LICENSE.

---