Embridge

Use Embridge when a list needs to stay readable as plain Markdown and still survive machine parsing, stable IDs, metadata, sync, and round trips through different tools.

ADOPTION MOMENT

When ordinary checkboxes stop being enough.

You want the file to remain comfortable for humans, but you also need agents and apps to know what changed, which item is which, and how to preserve unknown fields.

FILE PATH
  1. humanWrites tasks in a normal .md file.
  2. agentUpdates the same list without corrupting prose.
  3. appImports IDs, metadata, comments, and sections.
  4. fileRemains portable, diffable, and owned by you.

Validate a file (a validator)

Paste or edit Markdown in the textarea below. Or change the examples to get a feel for the format.

Valid Embridge
Examples
Mode marker
Lists 0
Items 0
IDs 0

Diagnostics

  • No diagnostics.

Parse outline

[]

When to use Embridge

Agent-edited backlogs

A coding agent can add, complete, split, or annotate tasks while preserving stable item IDs and human-written context.

Git-reviewable tasks

Keep project work in files that are easy to diff, review, branch, merge, and archive without asking a database for permission.

App import and export

Give a GUI a predictable Markdown shape instead of inventing a private schema that only one tool understands.

More than checkboxes, less than JSON

Use Markdown lists for the human layer, then add due dates, status, tags, comments, attachments, and document metadata as needed.

Why another task format?

Strict formats (JSON, YAML)
  • Machines parse perfectly
  • One typo can break the file
Embridge
Free-form text (notes, prose)
  • Easy to write and read
  • Machines have to guess

Embridge is Markdown with just enough structure: forgiving while you type, deterministic when a parser imports it.

Start simple, add structure when needed

BASIC EMBRIDGE

Start as ordinary Markdown.

- apples
- pears
- oranges

A plain list is valid enough for capture, notes, and low-ceremony tasks.

ADVANCED EMBRIDGE

Add structure when tools need round trips.

# To-do
- [ ] Fix login timeout bug
"repro in auth flow", prio: high, due: 2025-01-20, id: abc123d

# Done
- [x] Set up CI pipeline
id: ghi789a

IDs, metadata, comments, sections, and document hints appear when apps and agents need reliable references.

  • Markdown you know. Standard list markers, checkboxes, headings, links, and quoted descriptions.
  • Metadata on the next line. Comma-separated key: value pairs like prio: high, due: 2025-01-20, id: abc123d.
  • Stable IDs. Per-item id fields enable reliable automation, syncing, and merge conflict resolution.
  • Parser-friendly by design. The conformance fixtures define the expected parse tree for common and edge cases.
  • Everything optional. A task can be one line. Add structure only where it pays for itself.
  • Plain text ownership. Works in any editor, any OS, any git host. No database lock-in.

The bridge workflow

01 / HUMAN Edit the list

Write tasks in a normal Markdown file from any editor.

02 / AGENT Update by ID

The agent changes the intended item and keeps context intact.

03 / APP Import structure

A GUI reads sections, status, due dates, tags, and comments.

04 / FILE Stay portable

The .md file remains the source of truth.

# Sprint
- [ ] Add password timeout warning
prio: high, due: 2025-01-20, id: auth7kd
> @agent: found failing path in session renewal

- [x] Set up CI pipeline
id: ci92mqa
# Sprint
- [ ] Add password timeout warning {auth7kd} - 2 fields, 1 comment
- [x] Set up CI pipeline {ci92mqa}

That is the core bridge: human-readable text on one side, parser-readable structure on the other, with the file staying in the middle.

Builder path

Read the spec

Use the v0.1.1 reference for syntax, metadata, comments, blank-lines mode, and advanced expectations.

Specification

Inspect examples

Compare minimal lists, full advanced output, document metadata, attachments, and edge cases.

Example output

Run parser checks

The repository includes a JavaScript reference parser and conformance fixtures for expected parse behavior.

Reference parser

Preserve the file

Apps should keep UI-only state outside the file and preserve unknown fields for forward compatibility.

Conformance tests

Compared with nearby formats

Every example below stores the same short list — one open task with a priority, due date, and stable ID, plus one completed task. The left column shows the neighbouring format; the right shows the same data in Embridge.

List with line breaks 
apples
pears
oranges
Embridge 
- apples
- pears
- oranges

List with line breaksThree items, one per line — about as simple as it gets. But a bare line break carries no meaning: nothing marks these as list items, so the moment you need a checkbox, a sub-item, or a note, the format has nowhere to put it.

EmbridgeThe same three lines, each prefixed with a dash and a space. It reads just as cleanly, yet every line is now an addressable item ready to grow a [ ] checkbox, metadata, or nesting without changing shape.

GitHub Flavored Markdown 
# Sprint
- [ ] Fix login timeout bug
- [x] Set up CI pipeline
Embridge 
# Sprint
- [ ] Fix login timeout bug
prio: high, due: 2025-01-20, id: abc123d
- [x] Set up CI pipeline
id: ghi789a

GitHub Flavored MarkdownRenders everywhere and is instantly familiar, but it stops at the checkbox. There is no agreed way to attach a stable ID, a due date, or a comment, so every tool invents its own.

EmbridgeA near-superset of GFM: this file still renders as an ordinary task list on GitHub, while metadata lines add the structure apps and agents can round-trip.

JSON 
{
  "sections": [{
    "title": "Sprint",
    "items": [
      { "text": "Fix login timeout bug",
        "done": false, "prio": "high",
        "due": "2025-01-20", "id": "abc123d" },
      { "text": "Set up CI pipeline",
        "done": true, "id": "ghi789a" }
    ]
  }]
}
Embridge 
# Sprint
- [ ] Fix login timeout bug
prio: high, due: 2025-01-20, id: abc123d
- [x] Set up CI pipeline
id: ghi789a

JSONTrivial for machines and available in every language, but verbose, punctuation-heavy, and unforgiving — one stray comma breaks the file, and nobody captures a quick task by typing braces and quotes.

EmbridgeCarries the same fields with a fraction of the syntax and stays editable by hand in any text editor, with no schema or build step in the way.

YAML 
sections:
  - title: Sprint
    items:
      - text: Fix login timeout bug
        done: false
        prio: high
        due: 2025-01-20
        id: abc123d
      - text: Set up CI pipeline
        done: true
        id: ghi789a
Embridge 
# Sprint
- [ ] Fix login timeout bug
prio: high, due: 2025-01-20, id: abc123d
- [x] Set up CI pipeline
id: ghi789a

YAMLMore readable than JSON and good for config, but indentation is load-bearing and easy to break, and the spec hides sharp edges (the Norway problem, tabs, anchors) that surprise non-experts.

EmbridgeKeeps the calm, indentation-light feel while staying a true list you read top to bottom, rather than a nested data tree to navigate.

todo.txt 
(A) Fix login timeout bug +Sprint due:2025-01-20 id:abc123d
x Set up CI pipeline +Sprint id:ghi789a
Embridge 
# Sprint
- [ ] Fix login timeout bug
prio: high, due: 2025-01-20, id: abc123d
- [x] Set up CI pipeline
id: ghi789a

todo.txtPortable, line-oriented, and proven, but flat and symbol-heavy: priority, project, and dates are encoded in sigils, and there is no native nesting or sections.

EmbridgeStays Markdown-native and sectioned, so the same list groups, nests, and reads as prose while still parsing cleanly.

Hosted task tool (data dump) 
INSERT INTO tasks
  (id, section, text, done, prio, due) VALUES
  ('abc123d', 'Sprint', 'Fix login timeout bug',
   false, 'high', '2025-01-20'),
  ('ghi789a', 'Sprint', 'Set up CI pipeline',
   true, NULL, NULL);
Embridge 
# Sprint
- [ ] Fix login timeout bug
prio: high, due: 2025-01-20, id: abc123d
- [x] Set up CI pipeline
id: ghi789a

Hosted task toolPolished UIs and powerful queries, but the database owns the model. Exporting means a dump like this — readable by the vendor's importer, not by you, and rarely portable to another tool.

EmbridgeThe plain file is the source of truth. Any tool can read or write it, and the data stays with you even if a tool is abandoned.

Teach your AI agent Embridge

Your AI probably already knows how to use Embridge, but if you want to make sure ->
Select the agent systems you use, copy the text, paste it into any AI agent, and it installs a global Embridge skill on your device.

Claude Code — installs to ~/.claude/skills/embridge/SKILL.md. Hot-reloaded and available across every project; no restart needed.

Verify it worked: open a fresh agent session and ask it to create an Embridge to-do list. It should produce the format shown in the validator above — checkboxes, metadata lines, and stable id: values intact.

Every tool above consumes the same open Embridge skill body — as a SKILL.md skill where supported, or as a global rules / context file (AGENTS.md, .goosehints, QWEN.md) where not. One source, every harness. Logos belong to their respective owners; Embridge is not affiliated with or endorsed by them.

Start with a file

1

Create a Markdown file

Name it for the list: todo.md, shopping.md, packing.md, project.md, or anything else that belongs in plain text.

2

Add structure when needed

Use checkboxes, metadata lines, IDs, comments, and sections when tooling needs them.

Coming soon!