Workflows

A personal access token turns Kombine into something your other tools can read and write. Some things people use it for, with setups you can copy. The commands use the k helper from Using the API.

Let an AI agent manage your tasks

AI coding agents like Claude Code, Codex or Cursor can call the API for you. You ask in plain words (“what’s due this week?”, “add a task to review Anna’s PR tomorrow, high priority”, “log 45 minutes of deep work on the migration”) and the agent makes the requests. The quickest way is to install the Kombine skill. The steps below do the same by hand, for agents that don’t support skills.

1. Create a token for the agent. Start with Read only, and add Read & write for the areas you want it to change.
2. Put the token in an environment variable the agent can use, for example KOMBINE_TOKEN. Don’t paste it into the chat.
3. Tell the agent how to reach Kombine. Put this in its instructions file (CLAUDE.md, AGENTS.md, or 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.

Keep the “wait for my OK” line, at least at first. The agent writes straight to your real data.

To use it all the time, wrap a task you repeat in a script, and have the agent run the script. That’s how the Jira import below started: a Claude Code skill that runs the script with --dry-run, shows the list, and imports on a yes.

Import from another tool

Pull work from Jira, GitHub issues, Linear or anything with an API into Kombine, so your focus sessions and statistics include it. Run the import as often as you like: each item comes in once.

What makes that work is the task’s external_ref: a permanent link to the item it came from, written <source>:<id>, for example jira:PROJ-123 or github:kombine#42.

• The source is lowercase letters, digits and dashes. The id is anything without spaces.
• Each external_ref can be used once per account. Creating a second task with it fails with 409 and error code 4010.
• That includes deleted tasks. Deleting an imported task means “stop tracking this”, and the importer can’t bring it back.
• Set it when you create the task. It can’t be changed later.
• List what you’ve already imported, archived and deleted included: k "$API/tasks?external_ref_prefix=jira:"

Rules that keep imports pleasant:

• The source owns the title, priority and description. You own everything else: status, due date, energy, reminders. An importer shouldn’t overwrite those.
• Add a tag such as jira so imported tasks are easy to find and filter.

Jira

kombine-jira-import.sh imports the open Jira issues assigned to you:

• Title PROJ-123: summary, the issue link as description, tag jira.
• Jira priority maps to Kombine: Highest and High → High, Medium → Medium, Low and Lowest → Low.
• Issues already imported, archived or deleted are skipped.

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 which issues it picks with JIRA_JQL, and tag new tasks with an activity with KOMBINE_ACTIVITY="Work". Read the script before you run it; it’s short.

Shortcuts in your terminal

Small functions for your .zshrc or .bashrc. They need a token with tasks: Read & write and 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"
}

Timer in your status bar. With a timer: Read token, show what’s running on your phone in tmux, a menu bar tool, or your prompt:

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

It prints nothing when no timer is running. Refresh every 30 seconds or so; the token allows 60 requests a minute.

Your own dashboards

A token with only stats: Read (and sessions: Read for detail) is a safe way to feed your numbers somewhere else: a spreadsheet, Grafana, a weekly email to yourself.

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

The OpenAPI spec lists every field the stats and sessions endpoints return.