Omarchy To-do Plugin

A compact, persistent task manager for the Omarchy Shell. It provides list and Kanban views, recursive subtasks, deadlines, local reminders, configurable sorting, and optional Nextcloud Tasks synchronization through CalDAV.

Features

• Persistent task list in the Omarchy bar
• List and Kanban views
• Configurable Kanban lanes
• Drag-and-drop Kanban cards
• Manual task ordering by dragging
• Automatic sorting by priority or deadline
• Recursive subtasks
• Priorities with compact color accents
• Deadlines with a calendar picker and optional time
• Configurable date and 12/24-hour time formats
• Reminders expressed as an amount plus minutes, hours, days, or weeks
• Desktop notifications and selectable reminder sounds
• Configurable reminder volume
• Configurable fallback time for date-only deadlines
• Optional automatic Nextcloud Tasks synchronization through CalDAV
• Floating pinned board with configurable inactive opacity
• Separate floating Settings and Task Options windows while pinned
• Scrollable and responsive layouts
• Theme-aware colors from Omarchy Shell

Technical overview

The plugin is implemented in QML for Quickshell and uses small local helpers for functionality outside QML.

Local data

Runtime data is stored outside the plugin directory:

~/.local/state/omarchy/todo.json
~/.local/state/omarchy/todo-settings.json
~/.local/state/omarchy/todo-reminders.json

The Nextcloud app password is stored in the desktop keyring with secret-tool; it is not written to the settings file. The settings file contains the configured server URL and username, so it should not be committed or shared.

CalDAV behavior

Tasks are represented as standard iCalendar VTODO components. The synchronizer preserves the original iCalendar payload and updates controlled fields such as summary, status, priority, description, due date/time, categories, parent relationship and alarms.

The following extension fields preserve plugin-specific behavior across synchronization:

• X-OMARCHY-LANE for custom Kanban lanes
• X-OMARCHY-ORDER for manual ordering
• X-OMARCHY-DUE-TIME for reliable local time round-tripping

Recursive subtasks use RELATED-TO;RELTYPE=PARENT. Reminder offsets are also stored as VALARM data so compatible CalDAV clients can read them. Desktop notification delivery is handled locally by reminder-check.

Merge behavior

Synchronization compares local and remote LAST-MODIFIED/DTSTAMP values. The newer task wins. Deleted local tasks are removed remotely, while remote tasks are imported into the local task file. Writes use individual CalDAV PUT requests.

Reminder behavior

The shell checks reminders every five seconds. A reminder fires at:

deadline - configured reminder offset

Notifications are sent with notify-send; sounds are played with pw-play. Fired reminder signatures are stored locally to prevent duplicate alerts. Completed and deleted tasks are ignored. If a deadline has no explicit time, the configured date-only deadline time is used.

Window behavior

The pinned board is a Quickshell FloatingWindow. Settings and Task Options use separate top-level windows in pinned mode. dock-window listens for Hyprland window events, uses the Hyprland 0.55+ Lua dispatcher API to float the auxiliary windows, sizes them to 378 × 650, and places them beside the board.

Requirements

• A current Omarchy installation with Omarchy Shell and Quickshell
• Hyprland 0.55 or newer for pinned auxiliary-window docking
• Python 3
• jq
• libsecret / secret-tool
• libnotify / notify-send
• PipeWire tools / pw-play
• socat
• A notification daemon (provided by Omarchy Shell)
• Optional: a Nextcloud account with the Tasks app and a CalDAV task calendar

On Omarchy these dependencies are normally already available. Verify them with:

command -v python3 jq secret-tool notify-send pw-play socat

Installation

Recommended: install with Omarchy

Once this repository is published, install and enable it directly with:

omarchy plugin add https://github.com/TheMogli/ToDoma.git --enable

Omarchy will:

1. Clone the repository into a temporary staging directory.
2. Validate manifest.json and the plugin structure.
3. Install it as ~/.config/omarchy/plugins/todo.plugin using the manifest ID.
4. Rescan Omarchy Shell plugins.
5. Enable the bar widget and ask for its bar placement when run interactively.

For a non-interactive installation, explicitly accept the plugin trust prompt:

omarchy plugin add https://github.com/TheMogli/ToDoma.git --enable --yes

Plugins execute unsandboxed code inside Omarchy Shell. Review the repository before installing it.

Manual installation

Clone it directly into the Omarchy user-plugin directory. The destination directory must remain todo.plugin, because the plugin ID and helper paths use that name.

mkdir -p ~/.config/omarchy/plugins
git clone <repository-url> ~/.config/omarchy/plugins/todo.plugin

Alternatively, copy an existing checkout:

cp -a /path/to/omarchy-todo-plugin ~/.config/omarchy/plugins/todo.plugin

Ensure helper scripts are executable

chmod +x ~/.config/omarchy/plugins/todo.plugin/{nextcloud-sync,caldav-sync.py,reminder-check,dock-window}

Validate the plugin

omarchy plugin validate ~/.config/omarchy/plugins/todo.plugin

Enable the bar widget

Rescan plugins, then add the widget through Omarchy Shell settings:

omarchy-shell shell rescanPlugins

If the shell does not pick it up immediately:

omarchy restart shell

Select To-do List from the available bar widgets and place it in the desired bar section.

Nextcloud setup

1. In Nextcloud, create an app password under Personal settings → Security.
2. Open the plugin Settings window and select the Sync tab.
3. Enter the Nextcloud base URL or task-calendar URL.
4. Enter the username and app password.
5. Select Save, then Sync now.
6. Enable automatic sync and choose an interval if desired.

The app password is stored in the system keyring. If authentication fails, create a fresh app password and save it again.

Usage

• Left-click the bar widget to open the task panel.
• Add tasks from the field at the top.
• Use the List/Board button to switch views.
• Right-click a task to edit its details.
• Add subtasks from Task Options; right-click a subtask to edit it or add another nested level.
• In manual sort mode, drag tasks or cards to rearrange them.
• Pin the board to keep it as a floating desktop window.
• Configure synchronization, display, task sorting, reminders and Kanban lanes from the tabbed Settings window.

Privacy and security

This repository contains no task data, credentials, usernames, server URLs or reminder history. Runtime data stays under ~/.local/state/omarchy, and passwords stay in the desktop keyring.

Before publishing a fork, avoid adding any of the following:

• todo.json
• todo-settings.json
• todo-reminders.json
• keyring exports
• screenshots containing private task names or server URLs
• development backup files

Troubleshooting

The plugin is not listed

Confirm that the directory is named todo.plugin, validate it, and rescan:

omarchy plugin validate ~/.config/omarchy/plugins/todo.plugin
omarchy-shell shell rescanPlugins

Nextcloud authentication fails

Use an app password rather than the normal account password. Verify the server/calendar URL and username, then save the new app password.

Reminders do not make a sound

Confirm PipeWire is running and test the bundled system sound:

pw-play /usr/share/sounds/freedesktop/stereo/alarm-clock-elapsed.oga

Auxiliary windows are tiled

This plugin uses Hyprland's Lua dispatcher interface introduced in Hyprland 0.55. Confirm the installed version:

hyprctl version

Logs and validation

Run:

omarchy plugin validate ~/.config/omarchy/plugins/todo.plugin
hyprctl configerrors