Yarukoto
Self-hosted todo app

Your household's tasks,
on your server.

One container, one SQLite file. Apps for iPhone, Android, the Mac and Windows, shared lists for everyone at home, and your to-dos right inside Home Assistant.

Try the live demo View the source
Native everywhere
iPhone, Android, Mac and Windows.
No passwords
Sign in by scanning a QR.
Shared and private
One household, lists for each.
Home Assistant
Lists become HA to-do lists.
Design principle

Apps for iPhone, Android, Mac and Windows

A todo app lives in the gaps of your day: a lock screen, a menu bar, a glance between meetings. So Yarukoto uses each platform's own controls instead of drawing look-alikes, and it ships as a real app on each one. The web app is there too, served by your server, but it isn't the thing wrapped up and called an app.

Yarukoto on iPhone, picking a task's date from the system's native menu

iPhone

  • SwiftUI menus and date pickers, and Liquid Glass buttons, from the system itself.
  • Mark done and Snooze on the lock screen, caught natively at launch so they work with the app closed.
  • Haptics, swipe actions and a native, virtualized list you can drag to reorder.
Yarukoto on Android, picking a task's date in the system's Material date dialog

Android

  • Material date and time dialogs, built with Jetpack Compose rather than imitated.
  • Reminder actions run in a headless task, so tapping Mark done works even after the app has been swiped away.
  • Every tap is written to a durable queue first, so one made out of signal still lands.
Yarukoto's Mac window: a sidebar with the household's shared House, Groceries and Family lists, next to every task in the household

Mac

  • A real Mac Catalyst app with resizable panes, hover, right-click and a menu bar of its own.
  • Built for the keyboard: Tab between panes, arrows or j k to move, ⌘K to go anywhere. See the keys
  • A dense layout made for a pointer, text you can size with ⌘= and ⌘−, and a window that narrows to a slim column beside your work.
  • A menu bar icon with the count due today. Tick off Today's tasks from its menu, and closing the window keeps sync and reminders running. It can open at login, too.
  • System undo, so Edit ▸ Undo reads “Undo Complete Task”. Signed and notarized builds.

Download the desktop apps

The same app as your phone, in a window of its own, with the wide layout, keyboard shortcuts and vim keys. Connect it to your server, or explore with sample data first.

Download forMac Signed and notarized · .dmg
Download forWindows Windows 10 and 11 · .exe

The Windows installer isn't signed yet, so the first time it runs Windows asks you to choose More info, then Run anyway. Both apps check for new versions and offer the download when one is out. Every version is on the releases page.

Plan

Plan the week by dragging

Everything without a date, and everything overdue, waits beside a calendar. Find a task, drag it onto a day, and it's scheduled. A finger on a phone works as well as a mouse.

yarukoto.local:8080/calendar
  • Find it fast. Search, or filter by list, tag and date. What still needs a day comes first, highest priority on top.
  • Drop it anywhere. A column in the week for the days ahead, or a day in the month for later on.
  • Move several at once. Tap a few tasks, then drag them together.
  • Rebalance as you go. Anything already on the calendar drags to another day.
  • Room for the week. The day columns get the width, the month opens when you need it, and the task pane folds away from its own edge.

Just as easy on your phone

Tap Plan task and the tasks that need a day slide up from the bottom. Long-press one and the sheet steps aside, leaving the whole calendar to drop it on.

  • Carry several. Tap a few, then long-press any of them and they travel together.
  • Change your mind. Drag back to the button to cancel, and nothing moves.
  • Move what's planned. Drag a task out of the agenda onto another day in the month.
Multiple people

Accounts and shared lists

Everyone gets their own account, their own Inbox, tags, folders and saved filters. Lists start private; share one and everyone at home can see and edit it. The groceries are shared, your work list stays yours.

  • Shared lists carry a people icon in the sidebar, so it's always clear who sees what.
  • Activity shows what changed, in which list, as it syncs, and opens or restores the task behind each entry.
  • Each device signs in on its own and can be signed out from Settings without touching the others.
  • Removing someone hides, never deletes. Their devices are signed out and their private lists set aside; restoring them brings it all back.
Yarukoto's sidebar: Groceries, House and Family are shared lists with a people icon; Reading, Engineering and Admin are private
The Household section of Settings, listing three people and their devices, including a Home Assistant integration
Sign-in

Sign in with a QR code

Signing in is a QR code, in whichever direction has a camera. Every QR also shows a short code you can type, for the devices that don't.

Settings showing a one-time QR code for a new person named Nao to scan
1
A new phone scans. Pick New person, type their name, and they point their camera at the QR. It opens Yarukoto already signed in, with nothing to type, and works once.
The web app's sign-in screen showing a code, SSVK-X42D, and a QR code waiting for approval
2
Or your phone scans it. A browser, a Mac or Home Assistant shows a code and a QR. Scan it with a phone that's signed in, approve, and it finishes signing in by itself.
Home Assistant

Home Assistant integration

The Yarukoto integration turns the lists you pick into Home Assistant to-do lists. Tick off the groceries from a wall tablet, add to them by voice, or build an automation around what's due today.

  • Lists work both ways. Add, edit, tick off and delete; it shows up in the app on the next sync.
  • Saved filters come along too, like everything tagged #chores this week, ready to be ticked off.
  • It only sees what's shared. Home Assistant gets its own household token, approved by code like any device, and never sees anyone's private lists or Inbox.
  1. In HACS, add github.com/wyne/yarukoto-home-assistant as a custom repository and install Yarukoto.
  2. Add the integration and enter your server's address.
  3. Approve the code it shows from your phone, then pick lists and filters.
homeassistant.local:8123/todo
Home Assistant's To-do lists panel showing Yarukoto Groceries, House, Family and two saved filters, with the Groceries list open
The Chores this week saved filter as a Home Assistant to-do list, including a task's Markdown notes
The add field with 'pay water bill ~house fri 10am #bills !high' typed in: each token is tinted where it was typed, a suggestion offers !high to complete with Tab, and the date, priority and list buttons light up to match

Add tasks in one line

pay rent fri 6pm #home !high ~admin

The due date and time, the #tag, the !priority and the ~list come out of one line. Each one is tinted where you type it, so you can see what was understood before you commit, and anything unrecognized stays as the title. Tab completes the list, tag or priority being typed.

  • Repeats in the same line: every mon, wed, every 2 weeks, or every! 3 days to count from when it's done.
  • Subtasks, Markdown notes, tags, priorities, due dates and times.
  • Reminders, with Mark done and Snooze right on the notification.
  • Undo for completing and trashing, and Trash you can restore from.
Keyboard

Keyboard shortcuts, and vim keys

Every pane is a stop on Tab, the arrows move inside it, and Esc always lands you back on the list. Add a task, file it, open the next one and check off the last, without touching the trackpad.

  • Tab between panes: sidebar, add field, list and task. ⇧Tab goes back, and in a task it steps from title to notes to subtasks.
  • Arrows to move: ↑ ↓ through tasks or views, ⌘↑ ⌘↓ to either end, Space to peek and ↩ to edit.
  • Or vim, built in: j k, gg G, { } and the z folds work in every task list. See the vim keys
  • On the Mac, one key per place: ⌘1–⌘7 for views, ⌘S and ⌘D for the sidebar and task pane.
  • ⌘K for everything else: go to any list, tag, view or filter, change grouping and sort, or file the selected tasks with ⇧⌘M Move to List and ⇧⌘T Edit Tags. ⌘O finds a task by name, and both live in the same menu, so one key hands over to the other.
  • Hold ⌘ to see the keys labelled on the sidebar, the add field and search. ⌘/ lists every shortcut, built from the same table as the menu bar, so it is never out of date. All the keys
Vim keys

Vim keys in every task list

If your fingers already reach for j and k, the task list follows them. Move, jump between groups, fold them away and start a new task without reaching for the arrows. They're built into the list rather than added on top, so they're always on, in the Mac app, the Windows app and the browser alike.

Move

j k
Next and previous task
gg G
First and last task
⌃E ⌃Y
Scroll a row, the cursor stays put

Groups

} {
Next group, or back to this one's start
za zo zc
Toggle, open or fold this group
zM zR
Fold or open every group

Act

o i
Start a new task
/
Search
\
Show or hide the sidebar
  • Never in the way of typing. Letters only reach the list while it holds the keyboard, so a j in a task's title is just a j.
  • Folds you can land on. A folded group's header is a stop of its own, so j and k reach it and za opens it again.
  • Works with everything else. Space peeks at the task under the cursor, ↩ edits it and ⌘↩ checks it off, along with any others you've selected with ⇧↓.
  • The same in a browser, where o, / and \ stand in for the New Task, Find and sidebar keys the browser keeps for itself. All the list keys
Views

Views and saved filters

The same tasks, cut the way you think about them. Every view is a real link, so the one you live in is a bookmark away.

yarukoto.local:8080/today
Today view: due and overdue tasks from shared and private lists Plan view: a month grid above the day's agenda, with unscheduled tasks beside it ready to drag onto a day Browse with the Chores this week saved filter selected, showing four chores across the House list Task pane beside the list with a due time, priority, Markdown notes and subtasks
AI assistants

Connect AI assistants with MCP

The server speaks the Model Context Protocol at /mcp, so any assistant or agent that supports MCP can list, add, schedule and complete your tasks. It sees exactly what your account sees, and “friday” means friday in your time zone, not the container's.

# add to any MCP client
URL   https://todo.example.com/mcp
Auth  Bearer $YARUKOTO_TOKEN

# then just ask
› what's due on the house list?
Install

Install

One container, ghcr.io/wyne/yarukoto, built for amd64 and arm64. Your tasks live in a single SQLite file in the folder you mount, and survive every update.

  1. Make a folder and save this as compose.yaml in it. Set YARUKOTO_TZ to your time zone.
  2. Generate the owner's token. It's the admin credential, so make it random.
  3. Start it, then open http://<server>:8080.

Portainer, Dockge and Unraid's Compose Manager take the same file. To update: docker compose pull && docker compose up -d.

compose.yaml
services:
  yarukoto:
    image: ghcr.io/wyne/yarukoto:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      YARUKOTO_TOKEN: ${YARUKOTO_TOKEN:?set a token in .env}
      YARUKOTO_TZ: America/New_York   # your time zone
    volumes:
      - ./data:/data
terminal
echo "YARUKOTO_TOKEN=$(openssl rand -hex 32)" > .env
docker compose up -d

After installing

1

Sign in as the owner

Open the server in a browser or the app and use the token once. That account is the household's admin.

2

Bring in the household

Settings → Household → New person shows a QR. Each phone scans it and is signed in. No more tokens.

3

Add HTTPS for outside

Fine as plain HTTP at home. Before it faces the internet, put Caddy, Traefik or your NAS's reverse proxy in front.

4

Back up the snapshots

The server writes a snapshot to data/backups every day and keeps the newest seven. Point Restic, Hyper Backup or whatever you use at that folder. More on backups.

The installation guide covers each route in full, and every setting, like trash retention and history depth, is in the configuration reference.

Compared with a hosted todo app

Yarukoto Hosted service
Where the data lives One SQLite file you can copy Someone else's database
Cost A container on hardware you own Per month, per person, per tier
Signing in Scan a QR, no passwords Email, password, session
Your smart home Local Home Assistant integration A cloud integration, if any
Offline UI never waits on the network Varies; often read-only
If it shuts down It doesn't — you're running it Export and start over
Against other self-hosted options

Built for your phone, not merely available on it.

Many self-hosted task managers are built around the browser. Yarukoto treats iOS and Android as first-class clients, with offline edits that queue locally and sync when your server is reachable again.

Try it with sample data

Sample data mode runs the whole app client-side — no server needed. Everything stays on the device and resets when you reload.

Explore with sample data Read the setup guide