---
title: "AI Workflows: let an agent read and edit your tasks"
source: https://fieldbw.com/docs/tr-2/ai-workflows
---

# AI Workflows: let an agent read and edit your tasks

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](/docs/tr-2/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:

```bash
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.

```json
{
  "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:

```markdown
---
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:

```bash
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:

```bash
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

- [Vault Format](/docs/tr-2/vault-format) — the on-disk format the AI is reading and writing.
- [Getting Started](/docs/tr-2/getting-started) — set up the vault and the app.