ToDoz Logo ToDoz Docs & Guides
Open Web App
Complete Documentation

ToDoz User Guide & Self-Hosting Manual

Everything you need to master ToDoz: deterministic natural-language parsing, Boolean filter queries, deploying your own sovereign sync server, and connecting Google Calendar.

Quick Add Syntax

Type natural one-line commands. ToDoz deterministically tokenizes recognized keywords in under 5ms, highlights them in real-time, and strips them cleanly from the final title.

💡
Zero AI Latency: Unlike cloud tools that send your text to an LLM, ToDoz parses dates, repeats, priorities, and projects with a compiled deterministic lexer right on your device.
Keyword / Pattern Parsed Meaning Example
tomorrow, next week Relative calendar date target Submit report tomorrow
mon, next fri Closest target weekday or next week's weekday Team sync next fri
at 4pm, 16:30, noon Exact schedule time of day Doctor appointment at 16:30
45m, 1.5h, 2h Task duration (drawn as a block in time-grid) Deep work 2h at 9am
p1, p2, p3, p4 Priority level (p1 is urgent / red) Fix database leak p1
#Project, #"Two words" Destination project folder Grade thesis #Teaching
/Section Specific section inside the project Update notes #AI /Paper
%label or @label Attach one or multiple tags/labels Review pull request %Code
{oct 25} Hard deadline (independent of planned due date) Grant application {nov 15}
!30m before, !14:00 Exact notification reminder Catch flight !2h before

Mathematical Recurrence Engine

ToDoz supports standard schedules, multi-day recurring intervals, and completion-based rolling cycles.

Recurrence Command Behavior & Scheduling Rule
every day, every weekday Scheduled daily or Monday through Friday.
every other week Interval repetition (also: every 3 days, every quarter).
every mon, wed, fri at 9am Multi-day repeating time slots.
every 1st wed, every last fri Nth weekday of each month.
every last workday Smart business-day calendar scheduling (excludes weekends).
every! 3 days or after 10 days Completion-Relative Recurrence: Next due date is calculated strictly from the day you complete it, never piling up overdue backlog.
every day until dec 31 Bounded recurrence with fixed expiration date.

Boolean Filters & Smart Views

Create high-powered custom views using Boolean operators: & (AND), | (OR), ! (NOT), and parentheses. 

# Priority Work for Today or Overdue
(today | overdue) & #Research & p1

# High Priority Tasks Not in Inbox
!#inbox & (p1 | p2) & !subtask

# Multi-List Split View (Comma separated)
p1 & overdue, p4 & today, #Personal & 7 days
Filter Term Description Example
today, overdue Tasks due today or past their scheduled time today & p1
7 days Tasks scheduled in the next 7 days + overdue 7 days & #Teaching
##Project Matches project AND all its nested sub-projects ##SmartGate & overdue
%label* Wildcard tag search %dev* & !completed
due before: fri Date range boundaries (also due after:) due before: next monday
search: keyword Full-text search in title, notes, and labels search: dataset & p1

Calendar Views & Time-Grid

ToDoz features a responsive Google Calendar–style time grid rendered in four intuitive modes: Day, 3 Days, Week, and Month.

🖱️ Drag & Drop Scheduling

Drag any task block to another hour or another day. On touch screens, long-press to pick up and drop.

↔️ Bottom-Edge Duration

Grab the bottom border of any task block and drag downward to expand duration in 15-minute increments.

⌨️ Hotkey Navigation

Press D for Day, 3 for 3 Days, W for Week, M for Month, and G then C to open Calendar.

Self-Hosting Your Sync Server

Deploy your private ToDoz sync hub in minutes. Self-healing with Docker Compose, automated TLS certificates via Caddy, and zero data telemetry.

The easiest production setup. Caddy reverse-proxies the backend, terminates SSL, serves the web app at /app, and serves binary downloads.

1
Clone Repository & Configure Environment
Point your domain (e.g. todoz.yourdomain.com) to your server's IP address.
git clone https://github.com/polla-fattah/ToDoz.git /opt/todoz
cd /opt/todoz/server/deploy

# Create your environment file
cat << 'EOF' > .env
TASKFLOW_DOMAIN=todoz.yourdomain.com
TASKFLOW_PUBLIC_URL=https://todoz.yourdomain.com
EOF
2
Launch with Docker Compose
Starts the backend sync container and Caddy reverse proxy with auto-restart on boot.
docker compose --profile public up -d --build
3
Create User & Generate Device Invite Code
Run the embedded CLI tool inside the running container:
# Add your username
docker compose exec taskflow taskflow_server user add "YourName"

# Generate a 10-minute pairing code for your phone, PC, or browser
docker compose exec taskflow taskflow_server invite "YourName"

For servers running Debian or Ubuntu with native systemd: 

# Run automated installer
sudo TASKFLOW_DOMAIN=todoz.yourdomain.com bash server/deploy/install.sh

# Add user and invite
TF="sudo -u taskflow TASKFLOW_DB=/var/lib/taskflow/taskflow.sqlite /opt/taskflow/bin/taskflow_server"
$TF user add "YourName"
$TF invite "YourName"

Connecting Apps to Your Server

Pair Windows Desktop, Android, and Web Browser clients with zero password leakage.

A
Windows & Android App Pairing
1. Open ToDoz on your device.
2. Go to Settings $\rightarrow$ Sync.
3. Enter your server URL (e.g. https://todoz.example.com or your own self-hosted domain).
4. Enter the one-time code (e.g. ABCD-2345) generated by invite <name>.
5. Enter a device name (e.g. "Laptop" or "Pixel Phone").
6. Tap Connect. The server returns a cryptographic token and syncs all tasks immediately.
B
Web Browser Pairing
1. Navigate to https://todoz.example.com/app in your web browser.
2. Enter the one-time code from the server admin or generated in your ToDoz app under Settings $\rightarrow$ Sync.
3. The web app instantly signs in and caches nothing locally for maximum privacy.

Google Calendar Sync Guide

Keep your schedule synchronized with Google Calendar across all your personal devices.

✅
No Google Cloud setup required! Works immediately with any calendar app (Google Calendar, Apple Calendar, Outlook).
1
Generate your private iCal Feed URL
In the ToDoz app (or web at /app), open Settings $\rightarrow$ Calendar and integrations $\rightarrow$ Calendar feed (iCal). Turn it on and copy your unique address: 
https://todoz.example.com/ical/<your-private-token>.ics
2
Subscribe in Google Calendar
1. Open Google Calendar in your web browser.
2. In the left sidebar, click the $+$ sign next to "Other calendars".
3. Select "From URL".
4. Paste your https://todoz.example.com/ical/...ics URL and click Add calendar.
5. Google will now automatically display all your ToDoz tasks with dates and durations.

Enables two-way synchronization: tasks added in ToDoz appear in a dedicated "ToDoz" calendar in Google, and events modified in Google update your tasks.

1
Create Google Cloud OAuth Credentials
1. Go to Google Cloud Console and create a project named ToDoz.
2. Navigate to APIs & Services $\rightarrow$ Library, search for Google Calendar API and click Enable.
3. Under OAuth consent screen, select External, set app name to ToDoz, and add your Google account under Test Users.
4. Go to Credentials $\rightarrow$ Create Credentials $\rightarrow$ OAuth client ID.
5. Select Web application.
6. Under Authorized redirect URIs, add your server's callback address: 
https://todoz.example.com/google/callback
(Replace with your own self-hosted domain).
2
Configure Credentials in Server .env
On your server, edit /opt/todoz/server/deploy/.env:
TASKFLOW_PUBLIC_URL=https://todoz.example.com
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
Restart the container to activate the Google API service:
cd /opt/todoz/server/deploy && docker compose up -d
3
Connect in the ToDoz App
Open the app $\rightarrow$ Settings $\rightarrow$ Calendar and integrations $\rightarrow$ Google Calendar $\rightarrow$ tap Connect.
Sign in with your Google account. A dedicated ToDoz calendar will be created automatically in your Google account!

REST API & Inbound Webhooks

Integrate ToDoz with external automation tools (cURL, Python scripts, Raycast, GitHub Actions, Home Assistant).

Generate an API token in Settings $\rightarrow$ Calendar and integrations $\rightarrow$ API access, then send authenticated REST requests: 

# Create a task via Quick Add syntax over REST API
curl -X POST https://todoz.example.com/api/quick-add \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"line": "Submit publication revisions tomorrow 4pm p1 #Research"}'