Flux de travail

Un jeton d’accès personnel permet à tes autres outils de lire et d’écrire dans Kombine. Voici quelques usages courants, avec des configurations que tu peux copier. Les commandes utilisent l’outil k présenté dans Utiliser l’API.

Laisser un agent IA gérer tes tâches

Les agents de code IA comme Claude Code, Codex ou Cursor peuvent appeler l’API à ta place. Tu demandes en langage courant (« qu’est-ce qui est à rendre cette semaine ? », « ajoute une tâche pour relire la PR d’Anna demain, priorité haute », « enregistre 45 minutes de travail concentré sur la migration ») et l’agent envoie les requêtes. Le plus rapide est d’installer le skill Kombine. Les étapes ci-dessous font la même chose à la main, pour les agents qui ne prennent pas en charge les skills.

1. Crée un jeton pour l’agent. Commence avec Lecture seulement, puis ajoute Lecture et écriture pour les domaines que tu veux qu’il modifie.
2. Mets le jeton dans une variable d’environnement que l’agent peut utiliser, par exemple KOMBINE_TOKEN. Ne le colle pas dans le chat.
3. Explique à l’agent comment accéder à Kombine. Mets ceci dans son fichier d’instructions (CLAUDE.md, AGENTS.md ou équivalent) :

## 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.

Garde la ligne « wait for my OK », au moins au début. L’agent écrit directement dans tes vraies données.

Pour t’en servir au quotidien, mets une tâche que tu répètes dans un script et demande à l’agent de lancer ce script. C’est comme ça qu’a commencé l’import Jira ci-dessous : un skill Claude Code qui lance le script avec --dry-run, affiche la liste et importe si tu réponds oui.

Importer depuis un autre outil

Récupère dans Kombine le travail venant de Jira, des issues GitHub, de Linear ou de n’importe quel outil avec une API, pour que tes sessions de concentration et tes statistiques en tiennent compte. Lance l’import aussi souvent que tu veux : chaque élément n’arrive qu’une fois.

Ce qui rend ça possible, c’est le champ external_ref de la tâche : un lien permanent vers l’élément d’origine, écrit <source>:<id>, par exemple jira:PROJ-123 ou github:kombine#42.

• La source contient des lettres minuscules, des chiffres et des tirets. L’id peut être n’importe quoi sans espace.
• Chaque external_ref ne peut servir qu’une fois par compte. Créer une deuxième tâche avec le même échoue avec 409 et le code d’erreur 4010.
• Ça inclut les tâches supprimées. Supprimer une tâche importée veut dire « arrête de suivre ça », et l’outil d’import ne peut pas la faire revenir.
• Définis-le à la création de la tâche. Il ne peut plus être modifié ensuite.
• Liste ce que tu as déjà importé, y compris les tâches archivées et supprimées : k "$API/tasks?external_ref_prefix=jira:"

Des règles pour que les imports restent agréables :

• La source décide du titre, de la priorité et de la description. Tout le reste t’appartient : statut, échéance, énergie, rappels. Un outil d’import ne devrait pas les écraser.
• Ajoute une étiquette comme jira pour retrouver et filtrer facilement les tâches importées.

Jira

kombine-jira-import.sh importe les issues Jira ouvertes qui te sont assignées :

• Titre PROJ-123: summary, le lien de l’issue en description, l’étiquette jira.
• La priorité Jira devient celle de Kombine : Highest et High → Haute, Medium → Moyenne, Low et Lowest → Basse.
• Les issues déjà importées, archivées ou supprimées sont ignorées.

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

Change les issues sélectionnées avec JIRA_JQL, et associe une activité aux nouvelles tâches avec KOMBINE_ACTIVITY="Work". Lis le script avant de le lancer, il est court.

Raccourcis dans ton terminal

De petites fonctions pour ton .zshrc ou ton .bashrc. Elles demandent un jeton avec tasks : Lecture et écriture et sessions : Lecture et écriture.

# 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"
}

Le minuteur dans ta barre d’état. Avec un jeton timer : Lecture, affiche ce qui tourne sur ton téléphone dans tmux, un outil de barre de menus ou ton invite de commande :

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

Rien ne s’affiche quand aucun minuteur ne tourne. Rafraîchis toutes les 30 secondes environ : le jeton autorise 60 requêtes par minute.

Tes propres tableaux de bord

Un jeton avec seulement stats : Lecture (plus sessions : Lecture pour le détail) est un moyen sûr d’envoyer tes chiffres ailleurs : un tableur, Grafana, un e-mail hebdomadaire à toi-même.

# 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 spécification OpenAPI liste tous les champs renvoyés par les endpoints stats et sessions.