# My coding agents don't need a project management tool. They need markdown files. > Source: > Published: 2026-10-10 02:16:53+00:00 My coding agents used to read their tasks from a hosted tracker. They never needed one. They needed a folder of markdown files, and I needed a small board to look at them. This is how I worked that out, and the tool that came from it: [board.md](https://www.npmjs.com/package/board.md), a local board for the markdown task files already in your repo. I was about to pay for a database when the only reader of the data was an agent that reads text. I run several projects with coding agents. The tasks lived in Notion, on the free plan, and the agents pulled task details through its MCP server. It worked. But with a few projects I was close to the free plan's limit, and the next step would have cost me about $40 a month. It would have gone the same way with Jira, Monday or ClickUp: the limit and the price differ, the problem doesn't. Before paying, I looked at what the agents actually did with a task. They read the title, the notes and a few fields. Then they changed a status. That was all. An agent needs a file it can read and edit. One markdown file per task, in the repo, with the fields in YAML frontmatter and the notes below: ``` --- id: DEMO-4 title: "Projects CRUD" status: todo phase: P2 module: projects priority: P0 size: M branch: pr: --- # DEMO-4 Projects CRUD Soft delete. Names unique per account, ignoring case. ``` That format beats a hosted tracker for an agent in four ways: `main` always shows what is merged.`git log` on the file is the task's history. One of my projects already worked this way, with 88 task files. The agents were happy. I was the problem. I needed to see 88 files as columns and drag a card from one to the next. Nothing more. My first plan was something bigger, with a database behind it. I didn't need any of that: the files were already the database. The markdown kanban tools I looked at each wanted their own file layout, and I didn't want to convert files my agents already understood. So board.md reads the files you have. `npx boardmd init` looks at them and works out a config: the id format, the statuses, which fields become badges or filters. `npx boardmd serve` shows the board on localhost. [image: Demo: a card dragged from Todo to In progress changes one line in its file; boardmd new creates a task and its card appears on the board] "In progress" and "in review" are not written in any file. The board reads them from git each time it loads. `task/demo-4-projects-crud`, shows that task as in progress.` todo` gets a badge, so you can see the file is behind. This matters most with agents. My agent creates a branch, does the work and opens a pull request. The card moves across the board by itself, and nobody edits a status until the pull request sets it to done. When I drag a card, exactly one line of one file changes: ``` -status: todo +status: in-progress ``` This is the rule the tool is built around. The files belong to the agents and to code review. A board that re-serialises the YAML reorders keys, changes quotes and turns a status change into a noisy diff that conflicts with the next branch. So a drop does very little, on purpose: `status:` line is replaced. The key, spacing, quotes, any comment and the line ending stay as they were. A file with no `status:` line is refused, not given one. The board never commits or pushes; a banner lists the files you changed so you can. An agent gets the same guarantees as the board, through four commands. | Command | What it guarantees | |---|---| | `boardmd list --json` | Every open task with its fields, its file and its live state from git. | | `boardmd new "" --set phase=P2` | The next id, the right folder and file name, and frontmatter in the same order as the other files. | | `boardmd set DEMO-4 status=done pr=41` | Only those lines change. It warns if git shows the task in progress or in review. | | `boardmd check` | Every file is validated: ids, file names, folders, required fields, allowed values. | Before these existed, creating a task meant the agent guessed the next id, the folder and which fields to fill. Now a wrong guess gets an answer it can act on: ``` bash $ npx boardmd new "Half a task" --set priority=P9 Can't create the task: priority must be one of: P0, P1, P2; set phase (P1, P2), module, size (S, M, L) with --set <field>=<value>. ``` An agent also can't use a tool it doesn't know is there. So `boardmd init` offers to add a short section to `CLAUDE.md` or `AGENTS.md`, and a Claude Code skill. Both point at `boardmd guide`, which prints this repo's own rules from the config: where tasks live, the next id, the allowed values for each field and how branches are named. For Claude Code there is also a plugin. `/plugin marketplace add anojanst/board.md`, then `/plugin install boardmd@board-md`, adds `/boardmd:setup` to set a repo up and `/boardmd:board` to open its board. Three commands, from the root of a repo that has task files: ``` npm install --save-dev board.md npx boardmd init npx boardmd serve --open ``` `init` shows what it found and asks before writing anything. With no task files yet, it offers to create a `tasks/` folder with an example. You need Node 20 or later. git and the GitHub CLI are optional: without them the board works, just without branch and pull request state. It is free and open source (MIT): [npm](https://www.npmjs.com/package/board.md), [GitHub](https://github.com/anojanst/board.md). board.md is deliberately small, and these are the edges: `boardmd set`, or in your editor. If a team needs comments, assignments and reports, a hosted tracker earns its price. If your agents already keep tasks in markdown, point board.md at them and tell me what breaks.