Habilidad Principal de CarryCtx

CarryCtx proporciona estado del proyecto de primera clase y continuidad de contexto para agentes de codificación de IA. Permite a los agentes gestionar tareas, realizar un seguimiento granular del progreso, crear puntos de control de instantáneas, mantener grafos de dependencias de código AST, ejecutar servidores MCP stdio, aplicar presets de flujo de trabajo y preservar el contexto sin problemas a través de reinicios de sesión y árboles de trabajo de Git.

Cuándo Aplicar

Usa los comandos de CarryCtx cuando:

Iniciar una nueva tarea o sesión: Registrar la identidad del agente, iniciar sesión y restaurar el contexto (carryctx resume).
Gestionar tareas del proyecto: Crear, reclamar, iniciar, completar, bloquear o cancelar tareas (carryctx task ...).
Realizar un seguimiento granular del progreso: Registrar elementos estructurados de todo, block, risk y note.
Guardar estado / Puntos de control: Capturar el progreso actual del trabajo, el estado de git y el trabajo restante antes de finalizar sesiones o cambiar de enfoque.
Exploración del Grafo de Código: Escanear dependencias de módulos AST (carryctx graph scan) y exportar diagramas Mermaid/DOT/ASCII (carryctx graph export).
Integración de Herramientas de Agente de IA (MCP): Exponer el contexto del proyecto a Cursor / Windsurf / AGY a través del servidor stdio del Protocolo de Contexto de Modelo (carryctx mcp).
Estandarizar Flujos de Trabajo (Presets): Listar, inspeccionar y aplicar planos de flujo de trabajo del proyecto, reglas de codificación y personajes de agente (carryctx preset ...).
Trabajo de tareas en paralelo: Crear y aislar tareas en árboles de trabajo de Git dedicados (carryctx worktree ...).
Diagnosticar problemas de salud: Ejecutar carryctx doctor para detectar tareas huérfanas, hooks faltantes y problemas en la base de datos.
Podar datos antiguos: Usar carryctx project prune para limpiar tareas completadas y mantener la base de datos ligera.
Analíticas de Agente: Usar carryctx stats para auditar la duración de las sesiones del agente, métricas de tareas y exportar informes Markdown/CSV.
Buscar trabajo previo por contenido: Usar carryctx search "<consulta>" para encontrar tareas, elementos de progreso, puntos de control o decisiones por palabra clave en lugar de escribir SQL a mano o buscar en mensajes de confirmación.

Requisitos Previos

Instalar la CLI de CarryCtx (cargo install carryctx o binario precompilado).
Inicializar CarryCtx en el repositorio del proyecto: carryctx init.

Referencia Rápida

Acción	Comando	Propósito
Configuración de Agente	`carryctx agent register --name "$(whoami)" --provider "claude-code"`	Registrar identidad del agente
Agente Actual	`carryctx agent current`	Mostrar identidad del agente activo
Iniciar Sesión	`carryctx session start`	Comenzar sesión de trabajo rastreada
Reanudar Contexto	`carryctx resume`	Obtener tarea actual, progreso y próximas acciones
Crear Tarea	`carryctx task create --title "..." [--depends-on CTX-0001]`	Definir una nueva tarea
Reclamar Tarea	`carryctx task claim CTX-0001`	Asignar tarea al agente actual
Editar Tarea	`carryctx task edit CTX-0001 [--title ...] [--priority ...] [--description ...]`	Actualizar título, prioridad o descripción de la tarea
Iniciar Tarea	`carryctx task start CTX-0001`	Marcar tarea como en progreso
Rastrear Progreso	`carryctx progress <todo	block
Punto de Control	`carryctx checkpoint --done "..." --remaining "..."`	Guardar instantánea de estado semánticamente rica
Escanear Grafo de Código	`carryctx graph scan`	Extraer dependencias AST en grafo SQLite
Exportar Grafo	`carryctx graph export --type <mermaid	dot
Servidor MCP Stdio	`carryctx mcp`	Lanzar servidor MCP stdio con 6 herramientas de agente
Aplicar Preset	`carryctx preset apply <nombre_preset>`	Inyectar SOP de flujo de trabajo, reglas o personajes
Árbol de Trabajo	`carryctx worktree create CTX-0001`	Crear árbol de trabajo git aislado para la tarea
Finalizar Sesión	`carryctx session end`	Finalizar sesión de forma segura con punto de control
Doctor	`carryctx doctor`	Diagnosticar salud del proyecto
Instalar Hooks	`carryctx hooks install`	Punto de control automático en cada confirmación git
Podar Datos	`carryctx project prune --older-than 30`	Limpiar tareas completadas antiguas
Estadísticas de Agente	`carryctx stats [--markdown] [--output file.csv]`	Ver métricas y exportar informes de rendimiento
Decisión	`carryctx decision add --title "..." --task CTX-0001`	Registrar decisión arquitectónica
Transferencia	`carryctx handoff create --target <agente> --task CTX-0001`	Transferir trabajo entre agentes
Pausar Sesión	`carryctx session pause`	Pausar temporizador de sesión activa
Reanudar Sesión	`carryctx session resume`	Reanudar una sesión pausada
Buscar	`carryctx search "" [--type task	progress

Comportamiento de Salida (0.5.2+)

La salida de texto (el --format text predeterminado) es compacta por diseño: los comandos imprimen una línea corta por registro (Task created: CTX-0321, agent current imprime solo el nombre, las listas muestran display_id, estado y un título/resumen recortado) para que el contexto del agente se mantenga pequeño. Cuando se necesitan registros completos:

--verbose (bandera global) o [output] verbose = true en .carryctx/config.toml restaura el registro completo con formato bonito.
--fields display_id,status,summary (bandera global) o la tabla [output.fields] por comando recorta los registros a una lista permitida en texto y JSON.
--format json siempre devuelve el sobre completo.

La salida JSON no cambia y sigue siendo el contrato de máquina: cada éxito es un único sobre en stdout, cada error es un único sobre en stderr.

Flujo de Trabajo Estándar del Agente

1. Inicialización de Sesión y Restauración de Contexto

Al inicio de cualquier interacción o después de un reinicio del agente:

# Registrar y establecer identidad si aún no está configurada
carryctx agent current || carryctx agent register --name "claude" --provider "claude-code"

# Iniciar sesión y cargar contexto actual
carryctx session start
carryctx resume

Para pausar y reanudar sesiones:

carryctx session pause    # Pausar sesión activa (el temporizador se detiene)
carryctx session resume   # Reanudar una sesión pausada
carryctx session end      # Finalizar sesión con punto de control opcional
carryctx session abandon  # Finalizar sesión sin punto de control

2. Análisis de Dependencias de Código (Subsistema de Grafo)

Antes de modificar código o refactorizar módulos:

# 1. Escanear dependencias AST del código base
carryctx graph scan

# 2. Exportar subgrafo centrado en un módulo específico
carryctx graph export --type mermaid --focus "src/application/stats.rs" --depth 2

# 3. Exportar resumen arquitectónico ASCII compacto a nivel de módulo
carryctx graph export --type ascii --compact

3. Presets de Flujo de Trabajo e Inyección de Reglas

Inyectar procedimientos operativos estándar o directrices de codificación:

# Listar presets de flujo de trabajo disponibles
carryctx preset list

# Aplicar un preset de flujo de trabajo de corrección de errores estándar al proyecto actual
carryctx preset apply workflows/bugfix

4. Ciclo de Vida de la Tarea

# Listar tareas abiertas
carryctx task list --status ready

# Reclamar e iniciar tarea
carryctx task claim CTX-0001
carryctx task start CTX-0001

# Marcar tarea como finalizada después de la verificación
carryctx task complete CTX-0001

5. Seguimiento Granular del Progreso

A medida que avanza el trabajo, registra elementos de progreso estructurados:

carryctx progress todo "Escribir prueba unitaria para middleware de autenticación"
carryctx progress todo "Implementar validación de token JWT"
carryctx progress block "Esperando confirmación de especificación de endpoint de API"
carryctx progress risk "Cambio radical en dependencia upstream"
carryctx progress note "Se utilizó caché LRU para optimizar búsquedas de tokens"
# Marcar un todo como completado:
carryctx progress complete PX-0001

6. Creación de Puntos de Control

Guardar estado antes de finalizar una sesión, cambiar de tarea o transferir trabajo:

carryctx checkpoint \
  --done "Finalizados los endpoints de autenticación del backend" \
  --remaining "Integración del formulario de inicio de sesión del frontend" \
  --blocker "Ninguno"

7. Paralelismo con Árboles de Trabajo

Cuando se trabaja en tareas independientes simultáneamente:

carryctx worktree create CTX-0002
# Cambia al directorio de árbol de trabajo aislado vinculado a CTX-0002

7a. Registro de Decisiones y Transferencias

Capturar decisiones arquitectónicas y transferir trabajo entre agentes:

# Registrar una decisión arquitectónica (ADR) vinculada a una tarea
carryctx decision add --title "Usar SQLite para almacenamiento" --task CTX-0001

# Listar o buscar decisiones
carryctx decision list
carryctx decision search --keyword SQLite

# Marcar una decisión como reemplazada por una más reciente
carryctx decision supersede DEC-0001 --by DEC-0002

# Crear una transferencia para pasar trabajo a otro agente
carryctx handoff create --target <agent-ulid> --summary "Implementar la API" --task CTX-0001

# Aceptar, rechazar o cerrar una transferencia
carryctx handoff accept HO-0001
carryctx handoff reject HO-0001 --reason "No es mi área"
carryctx handoff close HO-0001

7b. Búsqueda de Texto Completo en el Historial del Proyecto

Encontrar trabajo previo por contenido, no por recordar qué rama o tarea lo modificó. Busca en títulos/descripciones de tareas, elementos de progreso, notas de puntos de control y decisiones, todo clasificado por relevancia:

# Buscar en todo
carryctx search "protocolo de trabajador markdown"

# Limitar a un tipo de entidad
carryctx search "backoff de reintento" --type checkpoint

# Reducir por el estado de la tarea propietaria o agente propietario
carryctx search "auth" --status in_progress
carryctx search "auth" --owner claude-code

Cada resultado incluye el ID de visualización de la tarea propietaria, el estado y (cuando se conoce) la rama en la que se trabajó. Úsalo antes de comenzar trabajo relacionado para evitar duplicar problemas ya resueltos, y antes de una transferencia para señalar al agente receptor el punto de control o decisión exacto que explica una elección anterior.

8. Finalización de Sesión e Informes

# Finalizar sesión de trabajo
carryctx session end

# Exportar informe de estadísticas del proyecto para descripción de PR o documentación
carryctx stats --markdown --output /tmp/project_stats.md

9. Integración del Protocolo de Contexto de Modelo (MCP)

Para conectar CarryCtx directamente a Cursor / Windsurf / AGY:

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

Herramientas MCP Expuestas:

carryctx_graph_explorer: Consultar, escanear y exportar el Grafo de Contexto del proyecto
carryctx_context_manager: Gestionar contexto persistente, puntos de control e instantáneas de estado
carryctx_task_manager: Gestionar tareas del proyecto, dependencias y prioridades
carryctx_progress_tracker: Gestionar progreso de tareas, notas y bloqueadores
carryctx_decision_logger: Registrar y buscar registros de decisiones arquitectónicas
carryctx_project_admin: Gestionar base de datos del proyecto, estadísticas, archivado en almacenamiento frío y configuración

10. Depuración y Solución de Problemas

Habilitar registro de depuración estructurado para diagnosticar problemas:

# Mostrar registros de depuración para operaciones de CarryCtx
export RUST_LOG=carryctx=debug
carryctx task list          # Ver salida de depuración antes de los resultados del comando

# Mostrar solo errores
export RUST_LOG=error
carryctx status

# Ejecutar diagnósticos
carryctx doctor             # Verificar salud del proyecto
carryctx doctor --json      # Salida de diagnóstico legible por máquina

Mejores Prácticas para Agentes de Codificación

Ejecuta siempre carryctx resume al iniciar: Reorienta al agente a la tarea actual y al progreso de inmediato.
Escanea el grafo de código antes de refactorizaciones grandes: carryctx graph scan previene dependencias upstream rotas.
Reclama tareas explícitamente: Evita la ejecución duplicada cuando varios agentes trabajan en el mismo repositorio.
Usa elementos de progreso estructurados: Mantén todo, done y block actualizados durante los pasos de ejecución.
Crea un punto de control antes de detenerte: Siempre crea un punto de control antes de ceder el control o completar trabajo complejo de varios pasos.
Ejecuta carryctx doctor en el primer uso o después de una actualización: Detecta deficiencias de configuración antes de que causen errores en tiempo de ejecución.

CarryCtx

¿Qué es CarryCtx?

Preguntar en tu IA favorita

Documentación