The Data Folder & File Format

The data folder (also called a “vault” in the Markdown world) is the folder where TandemLoop stores all your data. It consists entirely of ordinary text files—Markdown with YAML frontmatter—and you choose its location when you set up the app—locally or in iCloud Drive. This makes it readable by other tools, by AI agents, and of course by you with any text editor.

Folder Structure

{data folder}/
  AGENTS.md                  ← Instructions for AI agents
  _inbox/                    ← Quickly captured tasks (GTD inbox)
  bereiche/                  ← Your areas (one subfolder each)
    {area}/
      area_{slug}.md         ← Area metadata
      _projects/             ← Projects in the area
      _singles/              ← Standalone tasks directly in the area
      _folders/              ← Optional folders
        {folder}/
          fld_{slug}.md      ← Folder metadata
          _projects/
          _singles/
  _config/                   ← Configuration (tags, attributes, themes, display, language)
    tags.yaml
    attributes/              ← Custom attributes (one file per attribute)
      {key}.yaml
    themes/                  ← Themes (one file per theme)
      {key}.yaml
    agent.yaml               ← Your AI agent’s last run (written by the agent)
    language.yaml            ← Data folder language
  _views/                    ← Saved views (also in subfolders)
    vw_{slug}.yaml
  _proposals/                ← Proposals from the AI
    prop_{slug}.md
  _archive/                  ← Archived entities (don’t edit manually)
  _conflicts/                ← Saved iCloud conflict copies
  _system/                   ← Schema and generated reference documents

Directories with a _ prefix are system folders and are managed by the app.

Entity IDs and File Name Prefixes

Every entity has a stable UUID-based ID in the id field of its frontmatter. The file name is independent of it and follows a readable slug. Only views, view folders (vf_…), and proposals carry their slug in the ID. Older files may still have slug IDs (for example, area_arbeit).

The Data Contract

The file format follows three principles:

Tolerant reading: The app reads files even when fields are missing, unknown status values are present, or legacy files come from earlier versions. This ensures that an entry edited by hand or created by an AI agent doesn’t block the entire app.

Stable writing: When updating a file, the app preserves the order of existing fields and existing information. Unknown fields added by an external editor are kept. The app appends fields added later, such as a reminder (remind_at), to the end of the frontmatter; empty fields are written as null, and only a few, such as remind_at and repeat:, are omitted entirely as long as they aren’t set.

Machine-readable: Because these are plain-text Markdown files, AI agents and other tools can read the data folder directly. Working with AI Agents describes which changes they may make directly.

Custom Attributes

Custom attributes (in Settings under Attributes) add extra fields to tasks, projects, and milestones. Each attribute is a small YAML file in _config/attributes/—the file name is the attribute’s key:

key: client
name: Client
type: select
applies_to:
  - task
  - project
options:
  - ACME
  - Contoso
description: The client the work is done for.

The values are stored in the frontmatter of each file under attributes::

attributes:
  client: ACME
  budget: 12000
  acceptance: '2026-11-30'

• Types: text, number, date ('YYYY-MM-DD'), boolean (yes/no), select (one of the options), url (link).
• Keys consist of lowercase letters, digits, and underscores and must not match a built-in field such as status or due_date. A key can’t be changed later.
• Empty fields aren’t saved. Deleted attributes don’t remove values—they stay in the files and appear in the Inspector as a read-only row.
• In views, attributes are available as fields attributes.key for filtering, sorting, and grouping.

Recurring Tasks

The repeat rule is stored in the task’s frontmatter under repeat:, for example every Monday:

repeat:
  unit: week
  days: [mon]

unit is day, weekday, week, month, or year; optionally add every (interval), day or nth + weekday (monthly rules), from: completion (after completion), and until or count as the end. The app maintains the keys series, occurrence, and next itself. The complete reference for agents is in _system/docs/data-model.md.

Themes

Each theme is a YAML file under _config/themes/—the file name without extension is its key (northern-lights.yaml → northern-lights). A theme lists only the colors that differ from the default:

name: Northern Lights
description: Cool teal with dark surfaces.
appearance: system        # system, light, or dark
font_design: rounded      # default, rounded, serif, or monospaced
colors:
  primary:
    light: "#0F766E"
    dark: "#2DD4BF"
  danger: "#E5484D"       # one value applies to light and dark

Colors are written as hex values in quotation marks, with opacity as #RRGGBBAA. Which color keys exist, which are derived from others, and which defaults apply is documented in _system/docs/themes.md—TandemLoop maintains this reference itself so AI agents can design matching themes. Each device stores which theme is active on its own; the theme files themselves sync with the data folder.

The Relations Block

Every task, project, milestone, and folder file—except Inbox tasks—contains a short machine-readable section at the end of the file body that stores the parent links as relative Markdown links—here for a task in the project “Website Relaunch”:

<!-- tandemloop:relations:start -->
[Area: Work](../../../area_work.md) · [Project: Website Relaunch](../prj_website-relaunch.md)
<!-- tandemloop:relations:end -->

The app keeps this block up to date automatically, so you don’t need to edit it by hand; AI agents leave it out of new files and remove it when moving files. It makes the hierarchy traceable for tools and agents even without the app’s in-memory index.

Data Folder Language

The few texts TandemLoop writes into files itself—the labels in the relations block (Bereich: / Area: …), the headings in a task’s log (## Du — 21.3.2026 / ## You — 2026-03-21), the sections of a proposal (## Diskussion / ## Discussion), and the instructions for AI agents (AGENTS.md, _system/docs/)—follow the data folder’s language. It’s stored in _config/language.yaml:

language: en

New data folders are English; data folders without this file (from earlier versions) stay German. The data folder’s language doesn’t depend on the device language—so all devices write the same files. When reading, TandemLoop recognizes both variants.

Multiple Devices: Syncing Through iCloud Drive

TandemLoop has no server of its own and doesn’t send any data to the internet on its own. Because your data folder is an ordinary folder, you use it on multiple devices by putting it in iCloud Drive. iCloud keeps the files up to date between Mac, iPad, and iPhone; TandemLoop reads the same folder on each device and downloads missing files from iCloud as needed.