Habilidade Principal CarryCtx

O CarryCtx fornece estado de projeto de primeira classe e continuidade de contexto para agentes de codificação AI. Ele permite que agentes gerenciem tarefas, rastreiem progresso granular, criem snapshots de checkpoint, mantenham grafos de dependência de código AST, executem servidores MCP stdio, apliquem presets de fluxo de trabalho e preservem o contexto perfeitamente entre reinicializações de sessão e worktrees Git.

Quando Aplicar

Use comandos CarryCtx quando:

Iniciando uma nova tarefa ou sessão: Registre a identidade do agente, inicie a sessão e restaure o contexto (carryctx resume).
Gerenciando tarefas do projeto: Crie, reivindique, inicie, conclua, bloqueie ou cancele tarefas (carryctx task ...).
Rastreando progresso granular: Registre itens estruturados de todo, block, risk e note.
Salvando estado / Checkpoint: Capture o progresso atual do trabalho, status do git e trabalho restante antes de encerrar sessões ou mudar de foco.
Exploração de Grafo de Código: Escaneie dependências de módulo AST (carryctx graph scan) e exporte diagramas Mermaid/DOT/ASCII (carryctx graph export).
Integração de Ferramenta de Agente AI (MCP): Exponha o contexto do projeto para Cursor / Windsurf / AGY via servidor stdio Model Context Protocol (carryctx mcp).
Padronizando Fluxos de Trabalho (Presets): Liste, inspecione e aplique blueprints de fluxo de trabalho do projeto, regras de codificação e personas de agente (carryctx preset ...).
Trabalho em tarefas paralelas: Crie e isole tarefas em worktrees Git dedicadas (carryctx worktree ...).
Diagnosticando problemas de saúde: Execute carryctx doctor para identificar tarefas órfãs, hooks ausentes e problemas no banco de dados.
Limpando dados antigos: Use carryctx project prune para limpar tarefas concluídas e manter o banco de dados leve.
Analytics de Agente: Use carryctx stats para auditar durações de sessão do agente, métricas de tarefas e exportar relatórios em Markdown/CSV.
Encontrando trabalho anterior por conteúdo: Use carryctx search "<consulta>" para encontrar tarefas, itens de progresso, checkpoints ou decisões por palavra-chave, em vez de escrever SQL manualmente ou grep em mensagens de commit.

Pré-requisitos

Instale a CLI CarryCtx (cargo install carryctx ou binário pré-compilado).
Inicialize o CarryCtx no repositório do projeto: carryctx init.

Referência Rápida

Ação	Comando	Propósito
Configuração do Agente	`carryctx agent register --name "$(whoami)" --provider "claude-code"`	Registrar identidade do agente
Agente Atual	`carryctx agent current`	Mostrar identidade ativa do agente
Iniciar Sessão	`carryctx session start`	Iniciar sessão de trabalho rastreada
Retomar Contexto	`carryctx resume`	Buscar tarefa atual, progresso e próximas ações
Criar Tarefa	`carryctx task create --title "..." [--depends-on CTX-0001]`	Definir uma nova tarefa
Reivindicar Tarefa	`carryctx task claim CTX-0001`	Atribuir tarefa ao agente atual
Editar Tarefa	`carryctx task edit CTX-0001 [--title ...] [--priority ...] [--description ...]`	Atualizar título, prioridade ou descrição da tarefa
Iniciar Tarefa	`carryctx task start CTX-0001`	Marcar tarefa como em andamento
Rastrear Progresso	`carryctx progress <todo	block
Checkpoint	`carryctx checkpoint --done "..." --remaining "..."`	Salvar snapshot de estado semanticamente rico
Escanear Grafo de Código	`carryctx graph scan`	Extrair dependências AST para o grafo SQLite
Exportar Grafo	`carryctx graph export --type <mermaid	dot
Servidor Stdio MCP	`carryctx mcp`	Iniciar servidor stdio MCP com 6 ferramentas de agente
Aplicar Preset	`carryctx preset apply <nome_do_preset>`	Injetar SOPs de fluxo de trabalho, regras ou personas
Worktree	`carryctx worktree create CTX-0001`	Criar worktree git isolado para tarefa
Encerrar Sessão	`carryctx session end`	Encerrar sessão com checkpoint com segurança
Doctor	`carryctx doctor`	Diagnosticar saúde do projeto
Instalar Hooks	`carryctx hooks install`	Auto-checkpoint a cada commit git
Limpar Dados	`carryctx project prune --older-than 30`	Limpar tarefas concluídas antigas
Estatísticas do Agente	`carryctx stats [--markdown] [--output arquivo.csv]`	Visualizar métricas e exportar relatórios de desempenho
Decisão	`carryctx decision add --title "..." --task CTX-0001`	Registrar decisão arquitetural
Handoff	`carryctx handoff create --target <agente> --task CTX-0001`	Transferir trabalho entre agentes
Pausar Sessão	`carryctx session pause`	Pausar cronômetro da sessão ativa
Retomar Sessão	`carryctx session resume`	Retomar uma sessão pausada
Buscar	`carryctx search "" [--type task	progress

Comportamento de Saída (0.5.2+)

A saída de texto (o padrão --format text) é compacta por design: comandos de entidade imprimem uma linha curta por registro (Task created: CTX-0321, agent current imprime apenas o nome, listas mostram display_id, status e um título/resumo truncado) para que o contexto do agente permaneça pequeno. Quando registros completos são necessários:

--verbose (flag global) ou [output] verbose = true em .carryctx/config.toml restaura o registro completo formatado.
--fields display_id,status,summary (flag global) ou a tabela [output.fields] por comando reduz os registros a uma lista de permissões em texto e JSON.
--format json sempre retorna o envelope completo.

A saída JSON permanece inalterada e é o contrato de máquina: todo sucesso é um único envelope em stdout, todo erro é um único envelope em stderr.

Fluxo de Trabalho Padrão do Agente

1. Inicialização da Sessão e Restauração de Contexto

No início de qualquer interação ou após uma reinicialização do agente:

# Registrar e definir identidade se ainda não configurada
carryctx agent current || carryctx agent register --name "claude" --provider "claude-code"

# Iniciar sessão e carregar contexto atual
carryctx session start
carryctx resume

Para pausar e retomar sessões:

carryctx session pause    # Pausar sessão ativa (cronômetro para)
carryctx session resume   # Retomar uma sessão pausada
carryctx session end      # Encerrar sessão com checkpoint opcional
carryctx session abandon  # Encerrar sessão sem checkpoint

2. Análise de Dependência de Código (Subsistema Graph)

Antes de modificar código ou refatorar módulos:

# 1. Escanear dependências AST da base de código
carryctx graph scan

# 2. Exportar sub-grafo centrado em um módulo específico
carryctx graph export --type mermaid --focus "src/application/stats.rs" --depth 2

# 3. Exportar visão geral arquitetural ASCII compacta em nível de módulo
carryctx graph export --type ascii --compact

3. Presets de Fluxo de Trabalho e Injeção de Regras

Injetar procedimentos operacionais padrão ou diretrizes de codificação:

# Listar presets de fluxo de trabalho disponíveis
carryctx preset list

# Aplicar um preset de fluxo de trabalho de correção de bug padrão ao projeto atual
carryctx preset apply workflows/bugfix

4. Ciclo de Vida da Tarefa

# Listar tarefas abertas
carryctx task list --status ready

# Reivindicar e iniciar tarefa
carryctx task claim CTX-0001
carryctx task start CTX-0001

# Marcar tarefa como concluída após verificação
carryctx task complete CTX-0001

5. Rastreamento de Progresso Granular

Conforme o trabalho avança, registre itens de progresso estruturados:

carryctx progress todo "Escrever teste unitário para middleware de autenticação"
carryctx progress todo "Implementar validação de token JWT"
carryctx progress block "Aguardando confirmação da especificação do endpoint da API"
carryctx progress risk "Mudança crítica em dependência upstream"
carryctx progress note "Usado cache LRU para otimizar buscas de token"
# Marcar um todo como concluído:
carryctx progress complete PX-0001

6. Criando Checkpoints

Salve o estado antes de encerrar uma sessão, mudar de tarefa ou transferir trabalho:

carryctx checkpoint \
  --done "Finalizados endpoints de autenticação backend" \
  --remaining "Integração do formulário de login frontend" \
  --blocker "Nenhum"

7. Paralelismo com Worktrees

Ao trabalhar em tarefas independentes simultaneamente:

carryctx worktree create CTX-0002
# Alterna para diretório de worktree isolado vinculado a CTX-0002

7a. Registrando Decisões e Handoffs

Capture decisões arquiteturais e transfira trabalho entre agentes:

# Registrar uma decisão arquitetural (ADR) vinculada a uma tarefa
carryctx decision add --title "Usar SQLite para armazenamento" --task CTX-0001

# Listar ou pesquisar decisões
carryctx decision list
carryctx decision search --keyword SQLite

# Marcar uma decisão como substituída por uma mais recente
carryctx decision supersede DEC-0001 --by DEC-0002

# Criar um handoff para transferir trabalho para outro agente
carryctx handoff create --target <agente-ulid> --summary "Implementar a API" --task CTX-0001

# Aceitar, rejeitar ou fechar um handoff
carryctx handoff accept HO-0001
carryctx handoff reject HO-0001 --reason "Não é minha área"
carryctx handoff close HO-0001

7b. Busca Textual Completa no Histórico do Projeto

Encontre trabalho anterior pelo conteúdo, não lembrando qual branch ou tarefa o tocou. Pesquisa títulos/descrições de tarefas, itens de progresso, notas de checkpoint e decisões, todos classificados por relevância:

# Pesquisar tudo
carryctx search "protocolo de worker markdown"

# Escopo para um tipo de entidade
carryctx search "retry backoff" --type checkpoint

# Restringir pelo status da tarefa proprietária ou agente proprietário
carryctx search "auth" --status in_progress
carryctx search "auth" --owner claude-code

Cada resultado inclui o ID de exibição da tarefa proprietária, status e (quando conhecido) a branch em que foi trabalhada — use isso antes de iniciar trabalho relacionado para evitar duplicar problemas já resolvidos, e antes de um handoff para apontar o agente receptor para o checkpoint ou decisão exata que explica uma escolha anterior.

8. Encerrando Sessão e Relatórios

# Encerrar sessão de trabalho
carryctx session end

# Exportar relatório de estatísticas do projeto para descrição de PR ou documentação
carryctx stats --markdown --output /tmp/project_stats.md

9. Integração com Model Context Protocol (MCP)

Para conectar o CarryCtx diretamente ao Cursor / Windsurf / AGY:

{
  "mcpServers": {
    "carryctx": {
      "command": "carryctx",
      "args": ["mcp"]
    }
  }
}

Ferramentas MCP Expostas:

carryctx_graph_explorer: Consultar, escanear e exportar o Grafo de Contexto do projeto
carryctx_context_manager: Gerenciar contexto persistente, checkpoints e snapshots de estado
carryctx_task_manager: Gerenciar tarefas do projeto, dependências e prioridades
carryctx_progress_tracker: Gerenciar progresso da tarefa, notas e bloqueadores
carryctx_decision_logger: Registrar e pesquisar registros de decisão arquitetural
carryctx_project_admin: Gerenciar banco de dados do projeto, estatísticas, arquivamento em armazenamento frio e configuração

10. Depuração e Solução de Problemas

Ative o registro de depuração estruturado para diagnosticar problemas:

# Mostrar logs de depuração para operações CarryCtx
export RUST_LOG=carryctx=debug
carryctx task list          # Ver saída de depuração antes dos resultados do comando

# Mostrar apenas erros
export RUST_LOG=error
carryctx status

# Executar diagnósticos
carryctx doctor             # Verificar saúde do projeto
carryctx doctor --json      # Saída de diagnóstico legível por máquina

Melhores Práticas para Agentes de Codificação

Sempre execute carryctx resume ao iniciar: Reorienta o agente para a tarefa atual e progresso imediatamente.
Escaneie o grafo de código antes de grandes refatorações: carryctx graph scan evita dependências upstream quebradas.
Reivindique tarefas explicitamente: Previne execução duplicada quando vários agentes trabalham no mesmo repositório.
Use itens de progresso estruturados: Mantenha todo, done e block atualizados durante as etapas de execução.
Crie checkpoints antes de parar: Sempre crie um checkpoint antes de devolver o controle ou concluir trabalho complexo de várias etapas.
Execute carryctx doctor no primeiro uso ou após atualização: Revela lacunas de configuração antes que causem erros em tempo de execução.

CarryCtx Core Skill

O que é CarryCtx Core Skill?

Perguntar na sua IA favorita

Documentação