Tags

Tags let you label archived messages and notes with short keywords (for example email, client, project-x) and then browse or filter by those keywords. Tags are stored in each file's YAML frontmatter, so they travel with the file across sync, backups, and external editors.

How Tags Are Stored

Tags live in the tags: field of a markdown file's YAML frontmatter. Both YAML forms are supported and parsed identically:

Inline form:

---
title: "Client Meeting Followup"
date: 2026-04-26
tags: [email, client, project-x]
---

Block list form:

---
title: "Client Meeting Followup"
date: 2026-04-26
tags:
  - email
  - client
  - project-x
---

A few details to keep in mind:

• Case-sensitive storage. Foo, foo, and FOO are three distinct tags. The frontmatter pipeline preserves casing verbatim — what you type is what gets stored.

• Empty list is meaningful. tags: [] means "this file has been considered for tagging and currently has no tags." A missing tags: field means the file has never been touched by the tag UI. Both display the same way in the app.

• Auto-formatting on write. When the app writes tags back through the attach dialog, short tag arrays are emitted inline; longer arrays are folded to the block list form automatically.

• External edits are honored. If you edit the tags: field by hand in another editor, the app picks up the change on the next reload — the file is still the source of truth.

New notes are scaffolded with tags: [] so the field is always present in your workflow.

Attaching Tags

There are two ways to open the tag picker:

1. Tags button in the editor. Open an archived message in the Archives Detail view. The toolbar above the editor shows a Tags button alongside Copy, Send to Inbox, and Delete. Click it to open the tag picker.

2. Command palette. Run Attach tags to current document from the command palette (Mod+K), or use the attach-tags shortcut if you have one configured.

The picker shows every tag that already exists anywhere in your workspace, with the tags currently attached to this file pre-selected. From here you can:

• Toggle existing tags — click a row to add or remove it.

• Filter the list — type into the search input to narrow down by case-insensitive substring match.

• Create a new tag — when your input does not match any existing tag, a "Create tag X" row appears. Selecting it adds X to the workspace's tag universe and attaches it to the current file. New-tag matching is case-sensitive, so typing Bug when bug already exists will offer to create the new variant.

Confirm with the Confirm button (or Enter) to write the new tag list back to the file. Cancel (or Escape) to discard your changes.

Screenshot placeholder — tag picker dialog with a few selected tags and a "Create tag" row visible.

The Tags Page

Navigate to Tags from the toolbar (or run Go to Tags from the command palette, or use the nav-tags shortcut). The page uses a two-pane layout that mirrors Archives:

• Left pane — every unique tag in the workspace, sorted alphabetically (case-insensitive), each row showing the tag name and the number of files carrying it.

• Right pane — depends on what is selected:

  • No tag selected → a prompt to pick one from the left.

  • Tag selected, no document selected → the documents carrying that tag, in workspace order (the same order Archives uses).

  • Document selected → the same Archives Detail editor you get on the Archives page, with a back affordance to return to the document list.

The Tags page is read-only with respect to the tag set itself — you create and remove tags by attaching them through the picker, not by editing the page.

Screenshot placeholder — Tags page with a tag selected on the left and the matching document list on the right.

Filtering Search by Tag

Open the Search page. A Tags chip group appears in the search sidebar below the sort options. Each chip is a tag from your workspace — click to toggle it on or off.

Filtering semantics:

• AND across selected chips. A document is shown only if it carries every selected tag. Selecting email and client shows messages that have both, not either.

• Case-sensitive matching. Filter chips match storage exactly. If your workspace has both Bug and bug they appear as separate chips.

• Composes with the search query. Tag filtering and full-text search work together — the result set is the intersection.

• Clear button. When at least one chip is active, a Clear control appears next to the Tags label so you can drop the whole filter in one click.

If your workspace has no tags at all and you have no chips selected, the Tags section hides itself to keep the sidebar uncluttered.

Screenshot placeholder — search sidebar with two active tag chips and the matching results in the main pane.

Default Keyboard Shortcuts

The tag commands ship without default keybindings — both navTags and attachTags are empty strings out of the box. This is intentional: tag workflows vary widely between users, and we did not want to claim a chord that might collide with your own muscle memory.

To assign shortcuts of your own, open Settings (Mod+,) → Shortcuts and bind the two commands:

Both commands are also discoverable any time through the command palette (Mod+K), so even without bindings you can reach them in two keystrokes.

Cloud Sync Behavior

Tags are part of the file's frontmatter, so they sync exactly the same way the rest of the file does — there is no separate "tag stream" on the server.

This has one important consequence you should know about: because tags travel as ordinary file content, v1 does not semantically merge tag arrays. If you tag the same file on two devices before they sync, the result is a normal whole-file conflict and goes through the existing Sync conflict dialog (Keep Local / Keep Remote / Keep Both). After you choose, the surviving file's tag list is whatever was on that side — last-writer-wins. The other device's tag additions are not folded in.

A quick worked example:

1. Device A: attach client and urgent to meeting-followup.md, then sync.

2. Device B (offline since before step 1): attach email to the same file, then come online.

3. Sync detects "Both Modified" and shows the conflict dialog.

4. If you pick Keep Local on Device B, the file ends up with only email — client and urgent are dropped.

5. If you pick Keep Remote, the file ends up with client and urgent — email is dropped.

6. Keep Both preserves both versions side by side as meeting-followup.local.md and meeting-followup.remote.md, which you can reconcile by hand.

If you regularly tag from multiple devices, the safest pattern is to sync before and after a tagging session so the two sides never diverge on the same file.

A future version may merge tag arrays semantically (union of both sides), but that is not in v1.

Related

• Archives — where tagged messages are browsed and filtered

• Sync — full conflict-resolution workflow that the tag-edit caveat above plugs into

• Command Palette — discovering the nav-tags and attach-tags commands

• Settings and Themes — assigning your own keyboard shortcuts