Markdown Kanban Boards That Live in Your Git Repo

By Webster Noble

Markdown Kanban Boards That Live in Your Git Repo

Every project management tool I've ever used eventually held my tasks hostage. trello exports to JSON, Jira to a database I can't touch, Notion to whatever Notion does. A wave of FOSS terminal tools is flipping that around: the board is just a few markdown files sitting next to your code, and any TUI, editor, or AI agent can work with them. Here are three worth your time, all verified and installable today.

[!TIP]
The pitch in one line: your task list becomes greppable, diffable, version-controlled text — no server, no account, no export step when you leave.

Why Markdown Kanban Works

Think about what a task actually is: a line of text with a status. Storing that in someone else's cloud database means every read goes through their app, every migration is an export gamble, and your project's history lives in a place you can't grep.

With a markdown kanban board, the file is the source of truth. Columns are headings, cards are list items (or separate files, depending on the tool). You get real benefits from that one decision:

  • Git history is a free audit trail — who changed what task, when, and why
  • Any editor works — vim, VS Code, or the tool's own TUI
  • AI agents can read and write your tasks without an API integration, because plain files need no permission slip
  • Leaving costs nothing — the files outlive every tool

That last point is bigger than it sounds. Half the tools below were built specifically so coding agents could pick up tasks from the repo. which pairs naturally with running those agents against local models on your own box(Self-Host a Local LLM With Ollama).

What You Need

  • A terminal (you're a sysadmin reader, so yes)
  • Git for the versioning benefits. optional but recommended- Node.js for Backlog.md; nothing special for the others

Step-by-Step: Three Tools, Three Flavors

Step 1 — Backlog.md: The Full Workflow

Backlog.md is the most complete of the bunch: markdown-native tasks, acceptance criteria, milestones, dependencies, plus a live kanban view right in your terminal. MIT licensed, local-first, no telemetry.

npm i -g backlog.md
backlog init "My Awesome Project"
backlog task create "Write the backup script"
backlog board

backlog board paints a kanban board in your shell; backlog browser starts a local web UI (bound to 127.0.0.1 only) if you want drag-and-drop. Tasks land as .md files under backlog/ in your repo. One gotcha from the docs: if you skip installing and use npx, you must type npx backlog.md — plain npx backlog resolves to an unrelated package.

Where it shines is agent workflows: backlog init can wire up Claude Code, Codex, Gemini CLI, or Cursor via MCP, and the whole spec-driven loop (task → plan → code review) is built in. If you've been curious about self-hosted ChatGPT alternatives doing real work, this is a clean way to hand them structured jobs.

Step 2 — tiki: The Terminal-Native One

tiki takes a different angle: issues and docs, all markdown, all inside your project directory. Run tiki init in a repo and it even asks which AI assistant skills to set up before dropping you into a kanban view.

The basics are keyboard-first — F1 for kanban, F2 backlog, F3 roadmap — and you can define custom views with YAML filters (say, a "Blocked" column that's just status = 'blocked'). Two touches I genuinely like: piping creates a task (echo "Update shortcuts" | tiki), and there's a built-in dependency editor so "this blocks that" is explicit instead of tribal knowledge.

Step 3 — Taskell: The Old Reliable

Taskell has been around the longest and is the simplest mental model: one markdown file per board, columns are ## headings, cards are list items, subtasks are nested items. Vim-style keys, due dates, clean diffs, and it imports Trello boards and GitHub projects. handy if you're migrating off something.

brew install taskell        # macOS
dpkg -i taskell.deb         # Debian/Ubuntu: grab the .deb from GitHub releases first

It creates taskell.md by default. Because the format is dead simple, other tools interoperate with it freely — I've synced boards across machines with Syncthing without a hiccup.

Common Pitfalls

  • Merge conflicts on shared boards. Plain files mean two people editing the same board collide like any text file. Keep boards small, commit often, split per-person boards if needed.
  • Hand-editing Backlog.md task files. The CLI keeps metadata consistent; the docs recommend preferring commands over manual edits so fields don't drift.
  • The npx trap. npx backlog is not Backlog.md. Use npx backlog.md or install globally.
  • Changing Taskell's markdown settings later. Its config lets you redefine what titles/tasks/subtasks look like. older boards saved with different settings won't parse. Pick a format and stick with it.
  • Expecting team features. None of these do assignments, notifications, or permissions. That's the trade for plain text. for heavier collaboration you want a server-backed tool anyway.

Alternative Open-Source Options

  • Kanboard — self-hosted PHP kanban with a query language and automation rules; MIT licensed and runs on a LAMP-ish stack.
  • Wekan — full-featured open-source Trello clone (Node/Meteor) with realtime updates if you need actual multi-user boards.
  • Vikunja — a broader self-hosted task manager with list, gantt, kanban, and table views over the same data.

Those three hold a database. which is exactly what you're escaping — but they're honest, self-hosted escapes of another kind, and sometimes a team needs one.

References

Conclusion

Markdown kanban tools fix the quietest problem in project management: ownership. With Backlog.md you get a structured, agent-ready workflow; tiki gives terminal natives issues and docs in one TUI; Taskell stays the minimal classic. All three keep your tasks as text in your repo. readable in 2040, no subscription attached.

Why This Matters

Understanding markdown kanban boards that live in your git repo helps you make better decisions about your infrastructure. This post covers what you need to know and why it matters for day-to-day operations.

Try It

Pick the smallest project you maintain, run backlog init (or taskell) in its folder, and move one week of tasks into markdown. If you catch yourself grepping your own todo list and smiling — yeah, that's the feeling.