Repository navigation
To Do and Tasks
The shell has one task list with three possible homes: a local file, TickTick, or Google Tasks. Everything that shows tasks — the Dashboard's To Do page, the Timetable, At a Glance, the dock's Tasks widget, the island's checklist, the AI assistant — reads and writes through one neutral facade (Todo.qml), so the provider is a switch, not a different feature. Without any account, the same interface uses a local JSON file.
Settings → Accounts & Backup holds the provider selector (Config.options.todo.provider: local, ticktick, googleTasks; default local) and the two account cards. Changing provider changes where the Dashboard list reads and writes; the other provider's data is untouched. todo.refreshIntervalMinutes (default 5) sets the background refresh of remote lists.
| Local | TickTick | Google Tasks | |
|---|---|---|---|
| Due date | ✓ | ✓ | ✓ |
| Notes | ✓ | ✓ | ✓ |
| Priority (none / low / medium / high) | ✓ | ✓ | – |
| Tags | ✓ (editable) | shown, read-only | – |
| Sync | – | Inbox | one chosen task list |
The form never draws a field the provider cannot store: Todo.supportsDate / supportsNotes / supportsPriority / supportsTags decide what the new-task sheet offers, so you cannot type something that is silently dropped. A pill in the sheet's header names the provider, so you always know where a task will land.
The To Do page of the Sidebar Dashboard has Unfinished and Done tabs; a task with a due date floats to the top. Create a task with the floating button (it turns into a ✓ once there is a title) or Ctrl + N. The sheet has title, due date (No date, Today, Tomorrow or a date picker), priority, tags and notes. Hover a task for edit and delete; the check box completes it. Overdue tasks are marked, priority has its own colour (high = error, medium = tertiary, low = primary), and long titles fade at the edges.
Keyboard (while the page is focused, with the bottom group expanded; hold Ctrl to see the hints on the buttons):
- List — Ctrl + N new, Page Up / Page Down switch Unfinished / Done, Ctrl + R sync (TickTick), Ctrl + 1…9 complete or reopen the first nine tasks, arrows / Home / End select, Space / Enter toggle the selected one.
- Form — Ctrl + Enter save, Esc back, Ctrl + T title, Ctrl + D date, Ctrl + P next priority, Ctrl + G tags, Ctrl + O notes, Ctrl + 1 / 2 / 3 no date / today / tomorrow, Ctrl + 4…7 no / low / medium / high priority.
A task due today raises one notification ("Task due today: …", with the priority and the notes), checked every minute while any open task has a date, remembered per task and day so a reload never repeats it. It uses the internal notification channel, so DND and history apply.
- Timetable — dated tasks sit on their day, overdue ones are pinned to today, and undated ones are one backlog chip. See Calendar and Timetable.
-
Clock app — a task can have an alarm (
setAlarmForTask) which disappears when the task is done (Clock App). - At a Glance, the desktop To-Do widgets and the dock's Tasks widget.
- Launcher — type a task and press Ctrl + N to create it (Launcher & Search).
- AI — the assistant can list, create, update, complete and delete tasks, with the same approval gates as other writes (AI Integration).
With a TickTick access token, the list becomes your TickTick Inbox: create, complete, edit, delete and refresh all sync, and the widget refreshes itself every few minutes. A cloud icon on the page shows connected / syncing / not configured, doubles as a refresh button, and sends you to the right Settings page when not configured.
-
Settings → Accounts & Backup → TickTick. Open the TickTick Developer Center, register an app, and set its redirect URL to
http://localhost:18321. - Paste the Client ID and Client Secret and press Authorize & Generate Token. The browser opens, you approve
tasks:read tasks:write, and the access token is stored for you (scripts/ticktick/get_token.pyruns a one-shot local server on port 18321). You can also paste a token by hand.
The credentials and the token are kept in the system keyring (apiKeys.*, application illogical-impulse), with ii/.env (TICKTICK_CLIENT_ID, TICKTICK_CLIENT_SECRET, TICKTICK_ACCESS_TOKEN) only as a legacy fallback; neither is written to config.json or included in exported presets. A terminal alternative: scripts/ticktick-auth.sh.
Details: tasks are read from the Inbox project (inbox); a task without a due date gets "now" as a placeholder date, which is why the shell always asks hasDate instead of trusting date. Priority uses TickTick's scale (0 none, 1 low, 3 medium, 5 high) and the local store adopted the same integers.
Google Tasks uses the same Google OAuth client as Gmail, Calendar and Drive — see Google Cloud Setup; enable the Tasks API in the project. In Accounts & Backup → Google Tasks:
-
Connect Google Tasks — the browser opens (PKCE, loopback port 42070), you approve the
tasksscope only. Gmail keeps its own grant: scopes are requested incrementally, per feature. - Pick the Active Task List (Refresh task lists if you just created one). The choice is
todo.googleTasks.taskListId. - If Google revokes or expires the authorization — or the Tasks API is not enabled in the project, which the page detects and explains — a Reauthorize button appears.
Account and refresh token are stored in the keyring (google_tasks_accounts). scripts/google_tasks/api.py is a standard-library REST client: tokens and payloads go over stdin (never in the process arguments, where ps could see them), it paginates fully, and quotes every id. Mutations are queued so two quick edits cannot race. Editing uses PATCH /tasks/v1/lists/{list}/tasks/{task}; a due date is sent as a calendar date without shifting the day in time zones west of UTC.
~/.local/state/quickshell/user/todo.json, written atomically, normalized on load (content, done, date, hasDate, notes, priority, tags). Completed items are also kept in a short done history (the last 30), refreshed when an edit succeeds remotely.
| Piece | Role |
|---|---|
services/Todo.qml |
The facade: provider resolution, supports*, normalizeTask, addItem, updateItem, markDone, getTasksByDate, getUndatedTasks, getOverdueTasks, due notifications, AI entry points |
services/TickTickService.qml, scripts/ticktick/
|
TickTick adapter and token helper |
services/GoogleTasksService.qml, scripts/google/, scripts/google_tasks/api.py
|
Google OAuth (shared core) and the REST client |
modules/common/dashboardWidgets/todo/ |
TodoWidget, TaskList, NewTaskSheet
|
modules/settings/configs/TasksAccountsConfig.qml, widgets/CoreTickTickConfig.qml, widgets/CoreGoogleTasksConfig.qml
|
Settings |