Flujos de trabajo

Un token de acceso personal convierte Kombine en algo que tus otras herramientas pueden leer y escribir. Aquí tienes algunos usos habituales, con configuraciones que puedes copiar. Los comandos usan el helper k de Usar la API.

Deja que un agente de IA gestione tus tareas

Los agentes de programación con IA como Claude Code, Codex o Cursor pueden llamar a la API por ti. Pides las cosas con palabras normales (“¿qué vence esta semana?”, “añade una tarea para revisar el PR de Anna mañana, prioridad alta”, “registra 45 minutos de trabajo profundo en la migración”) y el agente hace las peticiones. Lo más rápido es instalar el skill de Kombine. Los pasos de abajo hacen lo mismo a mano, para agentes que no admiten skills.

1. Crea un token para el agente. Empieza solo con Read, y añade Read & write en las áreas que quieras que cambie.
2. Pon el token en una variable de entorno que el agente pueda usar, por ejemplo KOMBINE_TOKEN. No lo pegues en el chat.
3. Dile al agente cómo llegar a Kombine. Pon esto en su archivo de instrucciones (CLAUDE.md, AGENTS.md o similar):

## Kombine (my tasks and focus sessions)
- API: https://api.kombine.dev/v1, auth header `Authorization: Bearer $KOMBINE_TOKEN`
- Reference: https://api.kombine.dev/v1/openapi.json (read it before your first call)
- Creating anything: generate the `id` yourself (a lowercase UUID).
- Show me what you're about to create or change, and wait for my OK.
- Never print the token.

Mantén la línea de “wait for my OK”, al menos al principio. El agente escribe directamente en tus datos reales.

Para usarlo a diario, mete una tarea que repites en un script y haz que el agente ejecute el script. Así empezó la importación de Jira de abajo: un skill de Claude Code que ejecuta el script con --dry-run, muestra la lista e importa si dices que sí.

Importar desde otra herramienta

Trae trabajo de Jira, issues de GitHub, Linear o cualquier cosa con API a Kombine, para que tus sesiones de enfoque y tus estadísticas lo incluyan. Ejecuta la importación tantas veces como quieras: cada elemento entra una sola vez.

Lo que hace que funcione es el external_ref de la tarea: un enlace permanente al elemento del que viene, escrito como <source>:<id>, por ejemplo jira:PROJ-123 o github:kombine#42.

• La fuente son letras minúsculas, dígitos y guiones. El id es cualquier cosa sin espacios.
• Cada external_ref se puede usar una vez por cuenta. Crear una segunda tarea con él falla con 409 y el código de error 4010.
• Eso incluye las tareas eliminadas. Eliminar una tarea importada significa “deja de seguir esto”, y el importador no puede recuperarla.
• Defínelo al crear la tarea. No se puede cambiar después.
• Lista lo que ya has importado, incluidas las archivadas y eliminadas: k "$API/tasks?external_ref_prefix=jira:"

Reglas para que las importaciones sean agradables:

• La fuente manda en el título, la prioridad y la descripción. Tú mandas en todo lo demás: estado, fecha de vencimiento, energía, recordatorios. Un importador no debería sobrescribir eso.
• Añade una etiqueta como jira para que las tareas importadas sean fáciles de encontrar y filtrar.

Jira

kombine-jira-import.sh importa las issues abiertas de Jira asignadas a ti:

• Título PROJ-123: summary, el enlace a la issue como descripción, etiqueta jira.
• La prioridad de Jira se traduce a Kombine: Highest y High → High, Medium → Medium, Low y Lowest → Low.
• Las issues ya importadas, archivadas o eliminadas se omiten.

curl -O https://kombine.dev/examples/kombine-jira-import.sh && chmod +x kombine-jira-import.sh
export JIRA_SITE='your-company.atlassian.net' JIRA_EMAIL='you@company.com'
export JIRA_TOKEN='…'     # id.atlassian.com › Security › API tokens
export KOMBINE_TOKEN='…'  # tasks: Read & write, sessions: Read
./kombine-jira-import.sh --dry-run   # see what would be created
./kombine-jira-import.sh

Cambia qué issues elige con JIRA_JQL, y etiqueta las tareas nuevas con una actividad usando KOMBINE_ACTIVITY="Work". Lee el script antes de ejecutarlo; es corto.

Atajos en tu terminal

Pequeñas funciones para tu .zshrc o .bashrc. Necesitan un token con tasks: Read & write y sessions: Read & write.

# kadd "Call the bank" [LOW|MEDIUM|HIGH]
kadd() {
  k -X POST "$API/tasks" -d "$(jq -n --arg id "$(uuidgen | tr A-Z a-z)" --arg t "$1" --arg p "${2:-}" \
    '{id: $id, title: $t} + (if $p == "" then {} else {priority: $p} end)')" | jq -r '"added: \(.title)"'
}

# ktoday: open tasks due today or earlier
ktoday() {
  k "$API/tasks?limit=500" | jq -r --arg d "$(date +%F)" '
    .data[] | select(.status != "DONE" and .is_archived == false and .due_date != null and .due_date[0:10] <= $d)
    | "• \(.title)"'
}

# klog 45 "Code review": log a finished focus session of N minutes, ending now
klog() {
  local end start
  end=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  start=$(date -u -v-"$1"M +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d "-$1 min" +%Y-%m-%dT%H:%M:%SZ)
  k -X POST "$API/sessions" -d "$(jq -n --arg id "$(uuidgen | tr A-Z a-z)" --arg s "$start" --arg e "$end" \
    --argjson ms "$(( $1 * 60000 ))" --arg n "${2:-}" \
    '{id: $id, mode: "POMODORO", started_at: $s, ended_at: $e, duration_ms: $ms, note: $n}')" >/dev/null && echo "logged $1 min"
}

El temporizador en tu barra de estado. Con un token timer: Read, muestra lo que está corriendo en tu móvil en tmux, en una herramienta de la barra de menús o en tu prompt:

k "$API/timer/state" | jq -r '"\(.mode) · \(.status)"'

No imprime nada cuando no hay ningún temporizador en marcha. Actualízalo cada 30 segundos más o menos; el token permite 60 peticiones por minuto.

Tus propios paneles

Un token con solo stats: Read (y sessions: Read para el detalle) es una forma segura de llevar tus números a otro sitio: una hoja de cálculo, Grafana, un correo semanal para ti.

# sessions per day this month, and whether you hit your daily target, as CSV
k "$API/daily-snapshots?from=$(date +%Y-%m-01)&to=$(date +%F)" | jq -r '.snapshots[] | [.date, .sessions_completed, .achieved] | @csv'

# all-time totals
k "$API/stats/all-time" | jq '{totalFocusSessions, hours: ((.totalFocusSeconds // 0) / 3600 | floor), longestStreakLength}'

La especificación OpenAPI lista todos los campos que devuelven los endpoints de estadísticas y sesiones.