AI Workflows

Let an AI agent read and edit your TR-2 vault. No API, no MCP server — just point it at the folder.

Section: AI Workflows

TR-2’s “API” is the file system. Any AI that can read and write text files in a folder can read and write your task vault — the same vault you see in the app. No server to run, no auth tokens to manage, no schema to learn beyond the vault format.

The mental model

You and the AI are both editors of the same folder. TR-2 is one more editor. There is no “TR-2 backend” — when the AI saves a file, TR-2 sees the change and re-indexes; when you check a box in the app, the AI sees it on its next read.

        ~/Tasks/
        ┌──── inbox.md ────┐
   You ─┤      …           ├─ AI agent
        └──── Work/…       ┘
              ↑
              also TR-2 (the app)

Because the format is round-trip-safe, none of these editors can clobber bytes the others care about by accident.

Point your agent at the vault

Whatever your agent of choice is, give it filesystem access to the vault folder. Examples:

Claude Code

cd into the vault. Claude Code automatically sees the project context. Add a CLAUDE.md (or symlink your vault’s README.md) to give it a quick orientation:

cd ~/Tasks
claude

Cursor / VS Code with an agent extension

Open the vault folder as a workspace. The agent operates on the files like any other project.

A general-purpose MCP filesystem server

Configure the standard filesystem MCP server to expose the vault folder. Claude Desktop, ChatGPT, and other MCP clients will see the files as resources they can read and edit.

{
  "mcpServers": {
    "tasks": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Tasks"]
    }
  }
}

A one-off script

Read or write the .md files directly. There’s no special parser needed for most operations — append a - [ ] line to a project file and you’ve added a task.

What the AI sees

Drop the AI in front of your vault and it sees, at minimum:

  • README.md — TR-2 writes a short orientation here on first run, including the format conventions. Direct your agent to read it first.
  • inbox.md — anything you’ve captured but not processed.
  • <area>/<project>.md — project files, one per project.

A typical project file:

---
id: 7f3a2b
type: project
title: Website redesign
---

- [ ] Redesign homepage @next due:2026-05-25
- [*] Audit current layout
- [ ] Wireframe v2

## Done
- [x] Decommission old CMS done:2026-05-12

Everything the AI needs is in the lines. Status is the checkbox; lists are the tokens; the ## Done section is just a heading.

Conventions for agents

These aren’t enforced by TR-2 — they’re the conventions humans expect when they share a vault with an AI.

  1. Mark work-in-progress with [*]. When you start working a task, change [ ] to [*]. When you stop or finish, change to [ ] or [x]. This makes concurrent human/agent work legible.
  2. Add done:YYYY-MM-DD when you complete a task. TR-2 does this automatically; agents should too. The Done view sorts by this date.
  3. Don’t delete ^ids. If a task line ends in ^a1b2, leave the suffix alone — TR-2 uses it to track tasks across renames. You may delete one safely if it’s in your way; nothing breaks.
  4. Preserve unknown content. If you don’t know what a token, comment, frontmatter key, or section means, leave it. The format reserves space for future use.
  5. One write per logical edit. Read the file, apply your changes, write once. Don’t poll-and-rewrite.

Common patterns

Process the inbox

“Read inbox.md. For each item, propose a project file it belongs to (or ‘still inbox’). Move accepted items into the right project’s open list. Tag urgent ones @today.”

The agent reads inbox.md, decides on a destination, removes the line from inbox.md, and appends it to the destination project file. Round-trip safety means the rest of both files is untouched.

Pick up next actions

“List the next three actions across the vault — anything tagged @next that’s still open. Pick one to start; mark it [*].”

The agent greps for @next in .md files, filters by status [ ], picks one, rewrites that line as [*].

Weekly review

“Walk every project file. Flag anything open with no activity in 14 days as #stale. Summarise per area what shipped this week.”

The agent reads each file, checks done: dates against today, tags stale tasks, and writes a summary to a notes file you choose (TR-2 doesn’t care where).

Capture from somewhere else

A script can append a task without any TR-2-specific code:

echo "- [ ] $1 @today" >> ~/Tasks/inbox.md

Auditing what the AI did

Because the vault is plain markdown, every edit is a normal text diff. If you sync the vault with git, you get history for free:

cd ~/Tasks
git diff --since="1 day ago"     # what changed today
git log --stat -- Work/website.md # one project's history

There’s no separate audit log to keep. The diffs are the audit log.

See also