# Dumi — a to-do list in the Mac's notch that grows a voxel bonsai

> For AI agents: Dumi has no API, server or SDK. Its whole state is one JSON file on the Mac.
> Read it, edit it, write it back atomically. Dumi notices within about a second while running
> (or reads the file at launch), and a task you complete grows the bonsai as if the person had
> ticked it.

## File

    ~/Library/Application Support/Dumi/data.json
    (or the path in the ISLAND_DATA environment variable, if Dumi was started with it)

## Shape

A JSON object. Edit only `lists` and `tasks`; leave `sessions`, `timer`, `prefs` and `bonsai`
exactly as they are.

    lists[]:  { id: UUID, name: string }
    tasks[]:  { id: UUID (upper-case), listID: UUID, parentID?: UUID (subtask), title: string,
                notes?: string, due?: ISO-8601, starred: bool, createdAt: ISO-8601,
                completedAt?: ISO-8601 (present = done, absent = open),
                order: number (lower = higher in its list), rewarded?: bool (Dumi's; don't set) }

## Read

Open tasks: no `completedAt`. Top-level: no `parentID`. Order by `order` ascending within a list.

## Add

Append to `tasks`. Only `title` is required. A missing `id` is generated, a missing or unknown
`listID` goes to the first list, a missing `order` puts the task at the top of its list.

    { "title": "Book flights to Tokyo", "listID": "<a list id>", "due": "2026-09-18T00:00:00Z" }

## Complete / reopen / edit / delete

- Complete: set `completedAt` to now in UTC, e.g. "2026-09-14T09:30:00Z". Open subtasks complete
  with their parent. Dumi grants the cubes and sets `rewarded` itself.
- Reopen: remove `completedAt`.
- Edit: change title, notes, due, starred, order, listID freely.
- Delete: remove the object (and its subtasks). Lists: add/remove `{ id, name }` in `lists`; a
  removed list takes its tasks with it.

## Write

Read the whole file, change it, write the whole file to a temporary file in the same folder, then
rename it over data.json (atomic). Keep the other top-level keys.

## Rules

- Cubes are earned, never written: anything put in `bonsai` is ignored and overwritten.
- A completion earns cubes once; reopening and completing again earns nothing.
- Invalid or half-written JSON is ignored until the next complete write.
- Dumi saves ~0.5 s after the person's last change; an edit in that window may be overwritten —
  read again if a write seems not to have taken.

Full page: https://dumitasks.com/agents.html