ctxrs/ctx

Pesquisa de Histórico de Sessões do Agente ctx

Use ctx sempre que precisar consultar sessões anteriores de agentes de codificação. Essas transcrições podem conter intenções do usuário, decisões, cronogramas de trabalhos anteriores, tentativas passadas e o que funcionou ou falhou.

Use esta skill em dois modos:

• recuperação antes do trabalho, quando sessões anteriores podem conter decisões, comandos, falhas ou citações que afetam a tarefa atual;
• relatórios de pesquisa de histórico, quando o usuário pede a um agente ou subagente somente leitura para pesquisar um tópico histórico em sessões locais de agentes anteriores.

Pré-requisitos

• Exija que a CLI ctx esteja instalada e configurada. Se estiver faltando e a instalação de ferramentas for apropriada para a tarefa, instale-a com:

  curl -fsSL https://ctx.rs/install | sh
  

• A primeira configuração pode levar tempo enquanto ctx indexa sessões passadas. Se necessário, mantenha-o em execução em segundo plano ou no tmux, ou aguarde até que termine.

• Se ctx permanecer indisponível, diga que a pesquisa de histórico local está indisponível e não invente resultados.

Fluxo de Trabalho

1. Confirme que ctx está pronto ao iniciar a partir de um contexto frio:

   ctx status
   ctx sources
   

   Use ctx status --format json ou ctx sources --format json apenas quando um script precisar de campos exatos.

2. Pesquise com linguagem natural primeiro. Adicione termos ou filtros quando for útil:

   ctx search "<consulta>"
   ctx search "<consulta>" --refresh off
   ctx search "<consulta>" --provider codex
   ctx search "<consulta>" --workspace <workspace>
   ctx search "<consulta>" --file <caminho>
   ctx search "<consulta>" --since 30d
   ctx search "<consulta>" --term "<termo relacionado>" --term "<texto de erro>"
   ctx search "<consulta>" --session <ctx-session-id>
   ctx search "<consulta>" --verbose
   

   Use a saída de texto padrão para leitura pelo agente. Não adicione --format json para pesquisa ou exibição, a menos que você esteja direcionando para jq ou um script, ou precise de campos exatos legíveis por máquina. A saída JSON é muito maior e pode consumir rapidamente a janela de contexto.

   Quando o prompt solicitar um histórico de tópico ou relatório em várias sessões, execute várias consultas ctx search com diferentes redações e filtros para encontrar sessões promissoras. Use ctx search "<consulta>" --session <ctx-session-id> com escopo quando uma sessão parecer relevante e você precisar de correspondências densas no nível de eventos dessa sessão.

   A pesquisa padrão retorna sessões de agente principal para que a intenção humana e as decisões permaneçam proeminentes. Use --include-subagents quando detalhes de implementação, anotações de revisão de código, saída de teste ou rastros de falha de sessões de subagentes provavelmente forem importantes.

   Use --verbose quando precisar de IDs ctx completos, IDs de provedores, citações e comandos de acompanhamento copiáveis sem alternar para JSON.

   Você pode gravar a transcrição de uma sessão em um arquivo temporário, verificar o tamanho do arquivo e então ler as partes relevantes:

   ctx show session <ctx-session-id> --format markdown --out /tmp/ctx-session.md
   wc -c /tmp/ctx-session.md
   

   No Codex, ctx exclui a árvore de sessão ativa por padrão quando CODEX_THREAD_ID está disponível, de modo que o prompt atual e os subagentes não dominem a recuperação histórica. Use --include-current-session apenas quando a árvore de sessão ativa for o alvo.

3. Inspecione os resultados relevantes antes de confiar neles:

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>
   

4. Localize o material original do provedor quando a identidade da fonte ou dicas de continuação forem importantes. provider_session_id é o UUID de continuação do Codex:

   ctx locate event <ctx-event-id>
   ctx locate session <ctx-session-id>
   

5. Escreva uma transcrição das sessões relevantes quando você, o humano, ou outro agente precisar de um arquivo:

   ctx show session <ctx-session-id> --format markdown --out <caminho-de-saída>
   

Quando a Pesquisa Precisa Ser Restringida

Varie a consulta e use filtros de pesquisa antes de tirar conclusões. Os acompanhamentos úteis incluem pesquisa densa de eventos, pesquisa com escopo de sessão e verificações de localização da fonte:

ctx search "<variante da consulta>" --events --refresh off
ctx search "<consulta>" --session <ctx-session-id> --refresh off
ctx search "<consulta>" --include-subagents --refresh off
ctx show event <ctx-event-id> --window 5
ctx show session <ctx-session-id>
ctx locate event <ctx-event-id>
ctx locate session <ctx-session-id>

As janelas de resultados de pesquisa são limitadas. Não reivindique contagens exatas de todo o corpus ou uma auditoria completa a partir do número de resultados retornados. Se a conclusão solicitada não puder ser suportada com evidências de pesquisa, exibição e localização, declare esse limite e relate a evidência mais forte recuperada.

Para consultas avançadas ou enumeração determinística completa de eventos, use ctx list events. Leia a documentação completa de filtro, intervalo, cursor e saída antes de usar:

ctx docs show event-queries

Relatórios de Pesquisa de Histórico

Quando solicitado a pesquisar um tópico histórico, permaneça somente leitura, a menos que o usuário também solicite edições. O agente escreve o relatório; ctx apenas recupera material de origem local.

1. Reafirme o tópico, o escopo e o comprimento desejado se o prompt for ambíguo. Prefira relatórios concisos por padrão; use um relatório mais longo quando o usuário solicitar cronologia, alternativas ou evidências detalhadas.

2. Execute várias pesquisas direcionadas. Varie os termos da consulta entre a redação do usuário, nomes de arquivos ou módulos, texto de erro, comandos, nomes de branch e termos de decisão. Comece com ctx search "<tópico>", depois amplie com --term ou restrinja com --workspace, --provider, --file, --since ou --session <ctx-session-id>. Use --include-subagents quando revisões, tentativas de implementação, saída de teste ou rastros de falha provavelmente residirem em sessões delegadas. Adicione --refresh off quando o relatório não deve atualizar o índice ctx local.

3. Inspecione fontes focadas antes de tirar conclusões. Prefira ctx show event para um resultado mais os turnos próximos, e ctx show session quando o arco completo da sessão for importante:

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>
   

   Use o modo completo ou de log apenas quando a saída padrão omitir evidências necessárias.

4. Compare evidências entre sessões. Observe concordâncias, conflitos, resultados desatualizados e lacunas onde as pesquisas não encontraram evidências.

5. Produza o relatório como síntese do agente com citações.

Formato de relatório conciso:

• resposta ou descoberta;
• IDs ctx de suporte mais fortes;
• ressalvas ou lacunas importantes;
• opcional: próxima etapa de pesquisa ou verificação.

Formato de relatório longo:

• pergunta e escopo;
• método de pesquisa, incluindo consultas e filtros principais;
• descobertas ou cronologia;
• tabela de evidências com provedor, ID de sessão ctx, ID de evento ctx quando disponível e por que cada fonte é importante;
• conflitos, lacunas e acompanhamento sugerido.

Regras de Citação

• Cite material ctx quando ele afetar sua resposta ou implementação.
• Inclua o provedor, ID de sessão ctx, ID de evento ctx quando disponível, ID de sessão do provedor quando disponível.
• Se você sintetizar em vários trechos, rotule a conclusão como sua síntese e cite os trechos de suporte.
• Se um evento ou sessão citado estiver ausente da geração atual do Core, diga isso e considere se um ctx import explícito é apropriado.

Regras de Segurança

• Prefira saída de texto para leitura pelo agente. Use JSON apenas para scripts, jq ou extração exata de campos, e mantenha as saídas JSON pequenas.
• Não diga que ctx inferiu uma decisão, a menos que o texto citado afirme explicitamente essa decisão.
• Não afirme que ctx escreveu análise de modelo.
• Não cole transcrições brutas, grandes cargas JSON, segredos, tokens ou caminhos privados em um relatório voltado para o usuário. Resuma as evidências revisadas e cite apenas trechos curtos necessários para apoiar uma afirmação.
• Trate ~/.ctx, caminhos de transcrição do provedor e saída JSON como histórico local privado, a menos que o usuário solicite explicitamente compartilhar trechos revisados.