Build / validate (pull_request) Successful in 7m1s

Details

feat(tooling): mise run import-todoist — seed a heph store from Todoist

Turn the one-off Todoist importer into a documented, repeatable mise task.
Self-contained (spawns its own hephd), dry-run by default into a throwaway
store, `-- --commit` writes into the real store after backing it up. Auth via
TODOIST_TOKEN or TODOIST_OP_REF (op://). Mapping per design §6.2.1:
project hierarchy (+ Inbox→unfiled), priority→attention by meaning, due→do-date,
NL recurrence, descriptions + sub-tasks→canonical-context doc.

- mise-tasks/import-todoist
- docs/how-to/import-todoist.md (+ how-to index, reference mise-tasks table)
- changelog fragment

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-02 20:15:05 -07:00

2.6 KiB

Raw Permalink Blame History

title

modified

Import tasks from Todoist

A one-way seeding tool that mirrors your Todoist projects + active tasks into a heph store via the heph CLI. It does not sync back — run it once to bootstrap, then live in heph. Implemented as mise run import-todoist (mise-tasks/import-todoist).

Authentication

Set one of:

TODOIST_TOKEN — your Todoist API token directly; or
TODOIST_OP_REF — a 1Password op://… reference read via the op CLI.

export TODOIST_OP_REF="op://<vault>/<item>/credential"

(Put it in your shell profile so it's always available.)

Dry-run first (the default)

By default the tool imports into a throwaway store and prints a summary, so you can see exactly what would happen without touching your real data:

mise run import-todoist

DRY RUN: importing into a throwaway store (…); nothing real is touched.

=== IMPORT SUMMARY ===
projects created : 33/33
tasks created    : 317/317 top-level
sub-tasks         : 71 attached as context items
descriptions      : 93 context docs written
recurrences       : 95 applied, 0 fell back

Anything the recurrence parser can't handle is listed (imported without recurrence) so you can fix those by hand later with heph edit <id> --recur ….

Commit to your real store

mise run import-todoist -- --commit

This backs up your DB to heph.db.bak-<timestamp> first, then imports into your real store (default ~/.local/share/heph/heph.db, or $HEPH_DB). Close any open Neovim / stop hephd first — the daemon holds an exclusive lock on the DB, so the import can't open it while another daemon is running. (Alternatively, target a running daemon directly with -- --commit --socket <path>.)

To undo: cp heph.db.bak-<timestamp> heph.db.

How Todoist maps to heph

The full rationale is in design §6.2.1. In short:

Todoist	heph
project (hierarchical)	`project add --parent`; Inbox → unfiled
priority p1/p2/p3/p4	attention red / orange / blue / white (by the meaning of the p3=backlog, p4=default convention)
`due.date`	`--do-date` (a candidacy gate, not a deadline)
recurring `due.string`	`--recur` (natural-language parser)
description + sub-tasks	the task's canonical-context doc (sub-tasks as `- [ ]` context items, Fork A)
labels / sections	skipped (labels are negligible in practice)

install-heph — install heph/hephd and the plugin
design — §6.2.1 the Todoist study behind the mapping

2.6 KiB Raw Permalink Blame History