# Hydrant and Markdown files

Comparisons · September 26, 2026 · Henry Kobutra with Codex

![A synthetic terminal-style field of bracketed checkbox rows, check marks and aligned line geometry is framed by orange rules.](/log/images/hydrant-and-markdown/cover.webp)

*Choosing your tracker*

**Last reviewed: 2026-09-25**

Choose Markdown files when the task list is small, repository-local and better served by a text editor than a product. Choose Hydrant when several people or agents need to query and update the same work without inventing the tracker's rules inside every file and script.

Markdown is a strong baseline. It is plain text, widely readable and easy for coding agents to inspect.

## Files may be enough

A `TASKS.md` can hold a useful backlog in an afternoon. [Markdown](https://spec.commonmark.org/spec) gives it headings, links and lists. Git gives every change a history, branches and reviewable diffs. GitHub can render [task lists](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists) in repository conversations.

Files can also carry more discipline than critics admit. A repository may define stable IDs, owners, dependencies and acceptance checks in frontmatter or headings. Scripts can validate the format. CI can reject broken links or illegal transitions. Agents can update the same files through ordinary code review. Markdown does not inherently lack ownership conventions or automation.

For one maintainer and a modest backlog, that may be the entire answer. The tasks travel with the code, work offline, survive tool changes and require no separate account.

## The maintenance bill arrives in conventions

As the backlog grows, someone has to maintain the system around the text. Which field is authoritative? How do two agents avoid overwriting each other? Which tasks are ready, blocked, snoozed or waiting for review? How does a saved query stay current across hundreds of files? Who may change workflow or record acceptance?

Git can resolve text history, but it does not supply those task semantics. A team can build them with schemas, scripts, pull-request rules and careful habits. That is a reasonable engineering choice when the rules are small and stable.

Hydrant provides those shared records directly. It separates status, refinement and blockers; offers projects, cycles and saved views; and gives connected agents versioned, idempotent writes through MCP. Its [workflow pack](/help/agents/workflow-pack) can teach an agent a delivery procedure, although people still enforce its grants and sign-off boundaries. Hydrant does not run the agent or host the repository.

This project itself began with a Markdown backlog, then moved current work into Hydrant and kept the files as an archive. That transition is useful evidence, not a law. Keep the file while it remains the shortest honest system. Move to a tracker when maintaining the file's surrounding machinery becomes the larger job.

Contact: bots@hydrant.dev