---
title: "Getting Started with TR-2"
source: https://fieldbw.com/docs/tr-2/getting-started
---

# Getting Started with TR-2

## What is TR-2?

**Task Register TR-2** is a markdown-native task manager for macOS and iOS. Your vault is a folder you own; your tasks are plain `.md` files in that folder; the file system is the source of truth. TR-2 is one editor for those files — a text editor, an AI agent, and `git` are equals.

TR-2 is the file-native successor to TR-1: where the predecessor was a web app with a database, TR-2 is a native app over a folder of markdown. Same GTD bones; different substrate.

> **Coming soon.** macOS and iOS builds aren't public yet. [Drop your email](/tr-2#beta) and we'll let you know when the first builds go out.

## What you get

| Capability | How it works |
|---|---|
| **Plain-text storage** | One folder, one `.md` file per project, GFM checkboxes for tasks |
| **GTD lists** | Inbox, Today, Next, Scheduled, Someday, Done — all derived from tokens in the files |
| **Folders as areas** | Move a file in Finder; TR-2 follows |
| **AI-ready** | An AI with file-system access can read & edit the same vault you do |
| **Round-trip safe** | Bytes the app doesn't touch are preserved exactly |
| **Sync, your choice** | iCloud Drive, Dropbox, a git repo — TR-2 doesn't care |

## Set up your vault

1. **Pick a folder.** Anywhere on disk, anywhere your sync of choice can see. iCloud Drive, `~/Documents/Tasks`, a git repo — all fine.
2. **First launch** — TR-2 asks you to point it at the folder. It writes a small `.tr2` marker so it can recognise it next time.
3. **Capture something.** Press <kbd>⌘⇧I</kbd> from anywhere, type a task, hit return. It lands in `inbox.md` at the vault root.

That's the entire setup. There is no account, no database, no sign-in.

## A vault in 30 seconds

```
~/Tasks/                       # vault root — anywhere you like
  .tr2                         # format-version marker
  README.md                    # orientation, never rewritten
  inbox.md                     # quick-capture lives here
  Work/                        # a folder = a GTD area
    website.md                 # a file = a project
    Subarea/
      launch.md
  Personal/
    house.md
```

A vault is "any folder with a `.tr2` marker". Folders nest; areas nest with them. See [Vault Format](/docs/tr-2/vault-format) for the on-disk grammar.

## A task in 30 seconds

```markdown
- [ ] Ship the new homepage @today #marketing due:2026-05-25
- [*] Review the auth PR @next ^a1b2
- [x] Reply to investors done:2026-05-22
```

Three checkbox states (`[ ]` open · `[*]` in progress · `[x]` done), tokens that map to lists (`@today`, `@next`, `#tag`, `due:`), and an optional stable `^id`. See [Vault Format](/docs/tr-2/vault-format) for the full token grammar.

## Using the app

TR-2 is keyboard-first.

- <kbd>⌘⇧I</kbd> — quick capture to inbox
- <kbd>⌘K</kbd> — jump-to palette (any folder, project, or task)
- <kbd>↑</kbd>/<kbd>↓</kbd> — move selection
- <kbd>Return</kbd> — open / edit the selected task
- <kbd>Delete</kbd> — delete the selected task
- <kbd>⌘Z</kbd> / <kbd>⌘⇧Z</kbd> — undo / redo (every edit is reversible)

Right-click a task for the full context menu (status, today/next/someday, due date, add tag, move, delete). Select multiple tasks to bring up the bulk action bar.

## Connecting AI agents

There's no API to learn. Any AI with file-system access — Claude Code, Cursor, an MCP filesystem server, a one-off script — can read and edit your vault directly. Tasks are GitHub-flavored markdown checkboxes; the conventions are described in this docs site and in the `README.md` TR-2 writes into your vault on first run.

See [AI Workflows](/docs/tr-2/ai-workflows) for how to set this up and what to expect.

## Next steps

- [Vault Format](/docs/tr-2/vault-format) — the on-disk format in detail (folders, frontmatter, tokens, `## Done`, the round-trip guarantee).
- [AI Workflows](/docs/tr-2/ai-workflows) — point your agent at the vault, what it sees, what it can change.
- [GTD Primer](/docs/tr-2/gtd-primer) — the methodology TR-2's lists are shaped around.