      . . . .                                     . . . .
      | | | |                                     | | | |
      | | | |\                                   /| | | |
      | | | | \____                       ____/ | | | |
      | | | |      \_____________________/      | | | |
      | | | |      |    |    |    |    |      | | | |
______|_|_|_|______|____|____|____|____|______|_|_|_|______
================================================================

Embridge

Plain text lists for humans, AI agents, and apps

Embridge is a markdown-based item and task format. It stays readable in any editor, gives machines predictable structure, and keeps your data in a file you control.

Get Started Try Validator View on GitHub

Why another task format?

Strict formats (JSON, YAML)

Machines parse perfectly
One typo breaks everything

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.

Who it's for

Developers

Track project tasks in plain text, review changes in git, and keep the workflow inside your editor.

AI tool builders

Give agents a compact format they can read, update, and hand back without inventing a private schema.

Teams

Share task lists that survive tool changes because the content remains ordinary Markdown.

Examples

- apples
- pears
- oranges

Basic Embridge can be as small as an ordinary Markdown list.

# To-do
- [ ] Fix login timeout bug
"a description", prio: high, due: 2025-01-20, id: abc123d
- [ ] Add unit tests for auth module
tags: "testing, backend", id: def456a

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

Add checkboxes, metadata, due dates, and stable IDs only when tooling needs them.

# Setup steps
1. [ ] Install dependencies
prio: high, id: abc123d
2. [ ] Configure environment
id: def456a
3. [x] Run tests
id: ghi789a

Numbered markers work too. The marker is syntax; document order remains the source of ordering.

apples

pears

oranges

Blank-lines mode supports even looser human-authored lists when document metadata opts in.

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.

Perfect for

~ Project backlogs

> AI agent handoffs

# Personal task files

@ Team checklists

* Meeting action items

! Bug trackers

One file, many tools

todo.md

Your single source of truth

AI AI Agents

</> Your Editor

App Apps

The file owns the content. Editors, agents, apps, and sync layers can change without moving the source of truth.

Design principles

Human-friendly first

Use a one-line item when that is enough. Add fields, descriptions, comments, and IDs when automation needs them.

The file is truth

The .md file owns the content. Apps keep UI-only state elsewhere. Delete an app, keep your tasks.

Forward compatible

Unknown fields are preserved. Apps can add custom metadata without breaking other readers.

Works offline

Edit anywhere, sync later. No SaaS required. Git-native history, auditing, and collaboration remain available.

Get started

1

Create a file

Open any text editor and save a new file as todo.md.

2

Write tasks

Use Markdown list markers. Add - [ ] for checkboxes and metadata on the next line when useful.

3

Use it anywhere

Commit to git, sync with any file service, or keep it local. Your tools read the file instead of owning it.

Full specification

Validate a file

Paste or edit Embridge Markdown. The browser-side validator checks structure, reports warnings, and shows the parse outline it inferred.

Mode marker

Lists 0

Items 0

IDs 0

Diagnostics

No diagnostics.

Parse outline

[]