Skip to main content
TaskForge 3.0: your AI can read your tasks.
← What's new

Your vault ships with its own AI instructions

Shipped in version 3.0.0

Point an AI coding agent at your vault and it has to guess your task format: which checkbox syntax you use, whether high priority is a symbol or a word, what your custom "Waiting" status looks like, how you name daily note files. Guess wrong and it writes a task your other tools can't read.

TaskForge now removes the guessing. Every vault gets a small set of files that describe, in plain language and in machine-readable JSON, exactly how your tasks are written: your dialect, your renamed fields, your date format, your folder rules. Any AI agent that can read files can read these, and from then on it edits your tasks the way you do. Nothing is sent anywhere; the files live in your vault like everything else in TaskForge.

What gets written

The contract lives in TaskForge/Settings/ by default. If you rename the TaskForge base folder, the contract follows it:

  • agents.md: a human- and agent-readable guide to your vault's task syntax: which inline task dialect you use, your custom status symbols, any task file fields you've renamed, your date format, and your folder and filename conventions.
  • dialect.json: the same information as agents.md, in machine-readable form, for tools that prefer structured data over prose.
  • spaces.json: your saved spaces (the custom lists you organize tasks into) and how an agent should add a task to each one.

The same folder also holds your TaskForge settings file (settings.json), which the agent-contract generator does not touch. It only owns agents.md, dialect.json, and spaces.json. TaskForge does not write anything to your vault root itself; the contract stays inside TaskForge/Settings/, the way your other saved-note files do.

How to use it

There's nothing to configure to get started. As soon as you're on a vault with this version of TaskForge, the files are generated automatically. To use them:

  1. Open your vault in Claude Code, Cursor, Codex, or any other AI coding tool.
  2. Ask it to read TaskForge/Settings/agents.md before adding or editing tasks. Use your configured base folder if you renamed it.

TaskForge generates agents.md, dialect.json, and spaces.json; it does not create a root CLAUDE.md or AGENTS.md. You can add a pointer in your own agent instruction file if you want it to load the contract automatically.

Nothing to install, no MCP server to configure, no API key. The files are just part of your vault.

If you ever change a setting that affects your task format (a status symbol, a date format, a renamed field, a custom space), TaskForge regenerates these files automatically so they never drift out of sync with reality. Regeneration is deterministic: if nothing about your format actually changed, the files on disk don't change either, so syncing the same vault across two devices doesn't create noisy diffs.

Settings

Find the controls at Settings, then AI & Agents:

  • Generate agent files: the master toggle. On by default. Turn it off and TaskForge removes every file it wrote (the TaskForge/Settings/ contract files) without touching anything else in your vault.
  • Last generated: when the files were last written, or "Never generated" if the toggle is off.
  • Regenerate now: force a fresh write immediately, useful if you want to confirm the files reflect your current settings without waiting for the next automatic trigger.
  • Folder: shows the name of the folder the files live in (TaskForge/Settings/ by default).
  • Files written: a collapsible list of every file path TaskForge generates, so you can see exactly what's in your vault before you commit it to git or sync it anywhere.

The settings folder

Settings and the agent contract share TaskForge/Settings/ by default. The base folder is configurable; check Settings → AI & Agents → Folder for the actual path in your vault.

Platform notes

The agent contract itself is generated identically on every platform: iOS, Android, macOS, and Windows all write the same files into the same vault folder. The AI tools that read the files (Claude Code, Cursor, Codex, and similar) run on your computer, not on your phone, so in practice you'll use this from macOS or Windows with your vault open in one of those tools. iOS and Android still generate and maintain the files whenever your vault is open there, so a vault kept in sync via iCloud or another sync tool stays current no matter which device last touched it.

Work from the terminal or an agent

The contract is what makes two other tools possible. The taskforge CLI reads and edits the same vault from any terminal, and the MCP server lets Claude Desktop and other clients do the same through a small set of tools. Both rely on the contract files described here, so keep "Generate agent files" on if you plan to use either.