Skip to content

Docs

The Markdown files

How a Hamloy project looks as files when it goes out or comes in, line by line, so you can read it, keep it, or write one by hand.

A project's lists can go out of Hamloy as plain Markdown files and come back in the same way. Each list is one file, and each item is one checkbox line with its details in a comment at the end, so the files read well in any editor or on any code host.

The files in an export

An export is one ZIP named after the project (pebble-lists.zip). In it:

File What it holds
backlog.md the tasks (keys B-)
requests.md the requests for you (keys R-)
questions.md the questions for you (keys Q-)
ideas.md, bugs.md, … one file for each list of your own
.hamloy/lists.md the names and key letters of your own lists, when you have some
.hamloy/views.md your saved views, when you have some

Claims, messages and the history are not in it. Neither are deleted items.

A list file

This is the backlog.md of the Pebble project, a habit tracker, as an export wrote it:

## Streaks

- [ ] Count streaks per habit <!-- id:B-j6e9 by:claude at:2026-10-10T00:08 needs:Q-8ur7 summary:"Days in a row per habit, with skipped and missed days" prio:high -->
  A skipped day keeps the streak; a missed one ends it.
  Tests for both.

## Design

- [ ] Show the week as dots <!-- id:B-25qb by:claude at:2026-10-10T00:08 prio:low area:ui for:codex -->

## Reminders

- [x] Daily reminders <!-- id:B-yriz by:claude at:2026-10-10T00:08 done:2026-10-10T00:08 done-by:claude -->
  - [x] Ask for notification permission <!-- id:B-00qt by:claude at:2026-10-10T00:08 done:2026-10-10T00:08 done-by:claude -->
  - [x] Schedule the reminder <!-- id:B-auim by:claude at:2026-10-10T00:08 done:2026-10-10T00:08 done-by:claude -->
  - [x] Settings screen for the time <!-- id:B-tnbl by:claude at:2026-10-10T00:08 done:2026-10-10T00:08 done-by:claude -->

How to read it:

  • Headings are the list's sections, at any level (##, ###).
  • - [ ] and - [x] are open and done items. A line indented under another is its subtask.
  • The lines under an item are its notes. A fenced code block in the notes stays as it is.
  • The comment holds the item's details as name:value words:
Word Means
id:B-j6e9 the item's key
by: and at: who added it, and when (UTC)
done: and done-by: when it was ticked, and by whom
needs:Q-8ur7 the items it waits on, comma-separated (see What waits on what)
summary:"…" the one line others read in the list
former:B-b929 a key it had before it moved to another list
anything else the item's own fields, like prio:high or for:codex

A value with spaces is in quotes.

Questions

In questions.md the options are the first lines under a question, the recommended one marked. An answered question carries its answer in the comment:

- [x] Should a skipped day break the streak? <!-- id:Q-8ur7 by:claude at:2026-10-10T00:08 done:2026-10-10T00:08 answer:"Let each habit choose" why:"Some habits are weekly" answered-by:you -->
  - No, a skipped day keeps it (recommended)
  - Yes, every day counts
  - Let each habit choose
  Most habit apps keep the streak on a planned day off.

Lines after the options are the question's notes. A question has no subtasks.

Your own lists and views

.hamloy/lists.md names each list of your own with its key letter, so it comes back with the same keys:

# Lists

More lists besides backlog.md, requests.md and questions.md. Each is a task list with its own key letter.

- ideas.md · keys I-

.hamloy/views.md has one line per saved view:

# Views

- [ ] Most urgent <!-- id:V-ed8w by:claude list:backlog layout:table sort:-prio show:prio,area -->
- [ ] By priority <!-- id:V-yqtx by:claude list:backlog layout:board group:prio order:high,medium,low -->
- [ ] Waiting <!-- id:V-pcbf by:codex list:backlog layout:list filter:blocked=waiting suggested why:"see what waits on your answers" -->

Writing one by hand

Your assistant writes lists in this format when it imports work kept somewhere else, and reads an export's files the same way. The comment is optional: - [ ] Add a widget for the home screen is a whole item. An item without a key gets a fresh one, and a key that is taken or belongs to another list is replaced, with whatever waited on the old key still waiting on it.

Limits

  • An import lands whole or not at all.
  • A list with an unfinished git merge in it (the lines from <<<<<<< to >>>>>>>) is refused: keep one version and bring it in again.
  • A list's text is at most 2 MB, and one import at most 2,000 items.
  • The same limits hold as for the tools: a title up to 1,000 characters, notes up to 20,000, a summary up to 160, a field value up to 200, and no items waiting on each other in a circle.

See Export for where the button is.