v0.2.0 · Notion delta sync
anikchand461/todoc

The task manager
your terminal
deserves.

Fast, beautiful, and built entirely in your shell. TUI dashboard, Kanban board, fuzzy search, Notion integration. No apps. No accounts.

Get started → ▶ See demo
install pip install todoc
~/projects/myapp
$ todoc list

──── ◈ T O D O C ────

# Priority St Task Tags
1 CRIT ○ Ship v2.0 release due:Mon
2 HIGH ○ Fix login bug #bug #backend
3 MED  ✓ Write unit tests #dev
4 LOW  ○ Update docs #docs

1/4 done · 3pending · 25% ████████████████████████████
24
commands available
4
priority levels
3
platforms supported
0
config required
interactive demo

See every command
in action

Click a command on the left to see exactly what appears in your terminal.

Commands
📋 list
➕ add
✅ done
◎ board
↳ subtask
🔎 search
📊 stats
🔔 notify
⚙ daemon
📤 export
🔗 notion-link
↑ push
↓ pull
$ todoc list --by priority

──── ◈ T O D O C · sorted by priority ────

# Priority St Task Tags
1 CRIT ○ Ship v2.0 release due:Mon
2 HIGH ○ Fix login bug #bug #backend
3 MED  ○ Write unit tests #dev
4 LOW  ✓ Update README #docs

1/4 done ·3pending ·25%████████████████████████████
$ todoc add "Fix login bug" -p high --tags "#bug"

✓ Task added
id5
taskFix login bug
priorityHIGH
tags#bug

$ todoc add "Ship v2" -p critical --tags "due:Mon"

✓ Task added
id6
taskShip v2
priorityCRIT
tagsdue:Mon
$ todoc done 1 3

2 tasks completed 🎉
#1Ship v2.0 release
#3Write unit tests
nice work — keep going!

tip: todoc done 1 2 5 ← bulk complete multiple at once
$ todoc board

──────── ◈ K A N B A N B O A R D ────────

○ TO DO (2)
HIGH
Fix login bug
#bug
LOW 
Update docs
◎ IN PROGRESS (1)
CRIT
Ship v2.0 release
due:Mon
✓ DONE (1)
MED 
Write tests

use: todoc status <id> doing ← move to In Progress
$ todoc subtask 1 "Write changelog" -p medium

✓ Subtask added
parent#1
subtask#5 Write changelog

$ todoc show 1

◈ Task #1
priorityCRIT
descriptionShip v2.0 release
subtasks (1):
#5 Write changelog medium
$ todoc stats

8
Total
3
Done
5
Pending
38%
Done rate
Progress ████████████████████████████████ 38%

── by priority ──
CRIT2 tasks
HIGH3 tasks
MED 2 tasks
LOW 1 task
$ todoc notify

⚠ Notified — 2 urgent task(s)
#1Ship v2.0 release
#2Fix login bug
Desktop notification sent.

Auto-fires at: 4h · 6h · 9h · 12h · 18h · 24h for pending tasks
$ todoc daemon start

✓ Plist written → ~/Library/LaunchAgents/com.todoc.notify.plist
✓ Daemon loaded — runs every 30 min
✓ Notifications fire at 4h, 6h, 9h, 12h, 18h, 24h

$ todoc daemon status

✓ Platform: Darwin · Check interval: every 30 min
✓ Notify milestones: [4, 6, 9, 12, 18, 24] hours
✓ Daemon is RUNNING

macOS · Linux (systemd/cron) · Windows (Task Scheduler)
$ todoc export -o backup.json

✓ Exported
8 task(s) → backup.json (json)

$ todoc export --format csv -o tasks.csv

✓ Exported
8 task(s) → tasks.csv (csv)

backup.json → full fidelity, ideal for backups
tasks.csv → opens directly in Excel / Google Sheets
$ todoc push

Connecting to Notion…
Comparing local ↔ Notion (delta mode)…

✓ Push complete ↑ · delta sync
✚ 2 created (IDs: 9, 10)
✎ 1 updated (ID: 5)
✕ 0 archived
— 7 unchanged · skipped
Database ID: abc123def456…

Run todoc notion-link --reset to update credentials.
$ todoc pull

Fetching changes from Notion…
Comparing Notion ↔ local (delta mode)…

✓ Pull complete ↓ · delta sync
✚ 1 added (ID: 11)
✎ 2 updated (IDs: 3, 7)
✕ 0 removed
— 8 unchanged · skipped
Local backup → ~/.todoc/tasks_before_pull.json

Only changed tasks merged. Run todoc list to verify.
why todoc

Built for the
terminal native

01
Interactive TUI

Full keyboard-driven dashboard via todoc tui. Add, edit, search, and manage tasks without typing any commands. Built with Textual.

02
Kanban Board

Visual todoc board with To Do / In Progress / Done columns. Move tasks with todoc status <id> doing.

03
Fuzzy Search

Type todoc search "lgin" --fuzzy and it finds "Fix login bug". Typo-tolerant matching ranked by quality score.

04
Auto Notifications

todoc daemon start installs a background scheduler. Fires at 4h, 6h, 9h, 12h, 18h, 24h. Works on macOS, Linux, Windows — no terminal needed.

05
Subtasks

Break tasks into steps with todoc subtask 1 "sub". Subtasks appear under their parent in todoc show. Deleting parent removes all children.

06
Zero Config

Install and go. Everything stored in ~/.todoc/tasks.json. No accounts, no cloud, no setup. Export to JSON or CSV anytime.

07
Notion Sync

Bi-directional sync with Notion via todoc push and todoc pull. Delta mode — only changed task IDs are created, updated, or archived. Unchanged rows are skipped, so large boards sync in seconds.

new feature

Notion Integration
re-imagined

Sync your tasks with Notion — without the wait. The new delta engine compares task IDs and only touches what actually changed.

🔍
Step 1 · Compare
todoc reads all Notion rows and your local tasks, then diffs them by TaskID — not by position or full file hash.
⚡
Step 2 · Patch
Only the rows that actually changed get a PATCH or POST API call. Unchanged tasks are silently skipped.
✅
Step 3 · Report
A per-ID summary shows exactly what was created, updated, archived, and skipped — no black-box "N tasks synced."
Before · Full Replace
✕ Archive all N Notion rows
✕ Re-upload all N tasks fresh
✕ N × 2 API calls every sync
✕ Slow on large boards
✕ Notion rate-limits you at scale
After · Delta Sync
✓ Diff by TaskID in memory
✓ Only changed rows → API calls
✓ Unchanged tasks silently skipped
✓ Sub-second on idle boards
✓ Respects Notion rate limits
Quick Setup · 30 seconds
1. Create a Notion integration at notion.so/my-integrations → copy the API key. 2. Share a Notion page with your integration and copy its page ID from the URL. 3. Run todoc notion-link — enter your token + page ID once, and todoc saves them. 4. Every subsequent todoc push or todoc pull is fully automatic — delta only.
Credentials stored in ~/.todoc/notion_creds.json (owner-read-only, chmod 600).  ·  todoc notion-link --reset to re-authenticate  ·  todoc notion-logout to revoke.
reference

Every command,
documented

Run todoc help for the full reference or todoc -s for a compact cheat sheet.

Creating & Viewing
addCreate a new task
listShow all tasks — done tasks have strikethrough
showFull detail + subtasks for one task
searchFull-text search + --fuzzy typo-tolerant mode
sortDisplay list sorted by id, priority, or created
statsDashboard: counts, progress bar, priority & status
boardKanban board — To Do / In Progress / Done
tuiInteractive keyboard-driven TUI dashboard
Updating & Removing
doneMark one or more tasks complete (bulk supported)
undoneReopen a completed task
editUpdate any field — only passed flags change
statusMove task between Kanban columns
subtaskAdd a subtask under a parent task
deleteRemove a task (also removes its subtasks)
clearRemove all completed tasks
resetWipe every task — complete reset
Notifications & I/O
notifyFire desktop notification for urgent tasks now
daemonBackground scheduler — auto-notify at 4h…24h
exportSave tasks to JSON or CSV
importRestore tasks from a JSON backup
helpFull per-command reference with examples
Notion Sync
notion-linkAuthenticate with Notion — enter token & page ID once
pushDelta-sync local → Notion (create/update/archive changed IDs only)
pullDelta-sync Notion → local (merge changed IDs, auto-backup first)
notion-logoutRemove saved Notion credentials
Common flags
-p / --prioritycritical · high · medium · lowmedium
--tagsFree-form info field
--pendingOnly unfinished tasks
--completedOnly finished tasks
--bySort: id · priority · createdid
--descReverse sort order
--fuzzy / -fFuzzy search mode
--force / -fSkip confirmation prompts
--formatExport: json or csvjson
-o / --outputWrite export to file
-s / --summaryCompact command cheat sheet
get started

Running in
30 seconds

1
Install from PyPI
Requires Python 3.10+. Installs typer and rich automatically.
$pip install todoc
2
Add your first task
The todoc command is now globally available.
$todoc add "My first task" -p high
3
Start the daemon
Auto-notifications at 4h, 6h, 9h… for pending tasks. Run once after install.
$todoc daemon start
4
Explore
Full reference or compact cheat sheet.
$todoc help
$todoc -s
ℹTasks stored in ~/.todoc/tasks.json. No telemetry, no internet required after install.

macOS notifications: pip install todoc[macos] + brew install terminal-notifier
$pip install todoc
Successfully installed todoc-0.1.0
$todoc add "Ship the feature" -p critical
✓ Task added · id: 1 · CRIT
$todoc add "Write tests" --tags "#dev"
✓ Task added · id: 2 · MED 
$todoc daemon start
✓ Daemon loaded — runs every 30 min
✓ Notifies at 4h · 6h · 9h · 12h · 18h · 24h
$todoc tui
Launching interactive dashboard...
$todoc -s
◈ todoc — command summary
add list done edit ...
$█