MarkdownTaskManager turns a folder of Markdown files into a Kanban board

One HTML file, no server, no database

The project describes itself as a standalone web application contained in a single HTML file, task-manager.html, which uses the browser's File System Access API to read and write directly to your local Markdown files. The description of it as a complete task management system that transforms your Markdown files into an interactive Kanban board, without database or server, targets developers, distributed teams and integration with AI assistants. The advantage list in the README is worth reading as a set of design commitments rather than marketing. Single file, easy to copy, share and maintain. 100% local, your data stays on your machine. Git compatible, so task files are versionable, syncable and diffable. Plain text readable, editable with any editor. No server, working entirely in the browser. Multi-project, with multiple projects each with history. Dark mode and responsive, with a light and dark theme and mobile support with touch drag and drop. And multilingual, in English, French, German and Simplified Chinese, with a French README at readmeFR.md. The build pipeline in package.json confirms the single-file promise, since the build script runs node build.mjs to produce one self-contained, dependency-free task-manager.html from src/, with only html-minifier-terser as a dev dependency.

How the data flow works between browser and disk

The README draws the architecture as a simple chain, and it is genuinely that simple. A single task-manager.html file runs in the browser, the browser talks to your files, and your files are kanban.md and archive.md on your disk. The application requests access to a folder, and if the folder is empty it creates kanban.md for your active tasks and archive.md for your archived tasks. You can give the project a name, and the project is remembered for the next session, with the application remembering the last 10 projects. Two consequences follow. First, there is no synchronisation problem because there is only one copy of the file, on your disk, and the browser is the editor. Second, the permission model is the browser's, since the user grants the application access to a chosen folder through a picker, and the README's advice to keep the single HTML file in one place and select the project folder each time is really about how the app remembers which folder to reopen.

The Markdown format and where the board state lives

The task files are structured Markdown with a configuration block at the top. The minimal kanban.md template sets a title, a Configuration section with columns, categories, users and tags, and then one heading per column, so the board structure is declared in the file rather than in application settings. The archive.md template is smaller, with a title, a note that it holds archived tasks, and an Archives section. The configuration keys are the interesting part of the design, because they are what let the same board shape travel with the project. Columns are defined as a list, categories as a list, users with an @ prefix, and tags with a # prefix. That means a team can agree on a vocabulary in the file itself, and a reviewer reading a diff sees column renames and new categories in the same file as the task moves. The downside is that the format is Markdown with conventions, not a schema, so the application has to be tolerant of hand-edits, which in practice means the parser is doing work that a database would have done for free.

Where the files go, and the gitignore question

There are three installation layouts, and the README recommends the first. Option 1 is a root installation, where you copy two files into your project root, kanban.md and archive.md, alongside src, package.json and README.md. Option 2 is a subdirectory installation, where the files live in a directory such as .tasks/, or docs/tasks/ or .kanban/, and you select that folder when opening the application. Option 3 is optional and is about whether to version the files at all.

# .gitignore
kanban.md
archive.md
# or
.tasks/

The README is not neutral on that last point. It says it is generally recommended to version task files to keep history and sync with the team. That is the correct advice for the collaborative case, since a git-tracked kanban.md gives you a per-task history and lets a merge conflict surface two people claiming the same task, which is a useful signal rather than a bug. It also means the task board lands in the repository and in code review, which some teams want and others find noisy.

One copy per project versus one central file

The second decision is where task-manager.html itself lives, and the README presents two options with their trade-offs stated plainly. Option A is one copy per project, where each project directory holds its own task-manager.html alongside kanban.md and archive.md. The advantages are complete autonomy for each project, that it works even if the central file is modified, and that it can be versioned with the project. The disadvantages are duplication of the HTML file and a manual update in each project. Option B is a single centralised file, which the README recommends, kept in an accessible folder such as ~/tools/ with the projects in ~/projects/ each holding only their two Markdown files. The advantages are a single file to maintain, automatic updates for all projects and disk space savings. The disadvantage is a dependency on an external file. The README's usage advice follows: keep the file in an accessible folder, create a shortcut or bookmark, open it and select the desired project folder, and the application remembers the last 10 projects. It also suggests an alias.

# ~/.bashrc or ~/.zshrc
alias tasks='open ~/tools/task-manager.html'  # macOS
alias tasks='xdg-open ~/tools/task-manager.html'  # Linux
alias tasks='start ~/tools/task-manager.html'  # Windows

The AI assistant workflow, and the templates that drive it

The part of the README that goes furthest beyond a Kanban board is the integration with AI assistants, and the stated goal is complete traceability of work done. The principle section lists what assistants such as Claude, ChatGPT, Copilot and Gemini can do against the files. Create tasks with a strict format in kanban.md, break down complex tasks into subtasks, update progress in real time, document the complete result in a Notes field, reference tasks in Git commits with a TASK-XXX identifier, and archive on demand only, not automatically. Each assistant gets its own configuration file that references AI_WORKFLOW.md, and the README tabulates the file names and locations for Claude with CLAUDE.md at the project root, GitHub Copilot with copilot-instructions.md in .github/, OpenAI CLI with OPENAI_CLI.md at the project root, ChatGPT with CHATGPT.md or a Custom GPT, Gemini with GEMINI.md or instructions.md, Qwen with QWEN.md or .qwenrc, and Codeium and Windsurf with instructions.md in .windsurf/ or .codeium/. Templates ship with the .exemple suffix for each of them. Installation is three copies.

# Required files
cp AI_WORKFLOW.md your-project/
cp kanban.md your-project/
cp archive.md your-project/

For Claude specifically you copy the template over the real file name, and for Claude Code the repository ships a dedicated skill directory that you copy into the skills folder and then restart the CLI to activate.

Where MarkdownTaskManager is the wrong tool

Three limits, and the first is browser support. The prerequisites call for Chrome 86+, Edge 86+ or Opera 72+, and the File System Access API is not available on Firefox or Safari. A task tool that a third of your team cannot open is not a team tool, and this is not a niche limitation because Firefox and Safari are two of the three major desktop browsers. The second is concurrency. The source of truth is a file on one disk, opened through a browser permission grant, with no locking, no merge semantics and no server-side conflict resolution. Two people editing the same board will overwrite each other, and the only coordination mechanism is git, which works for commits but not for two people working at the same time. The third is scope. There is no account system, no assignment enforcement, no due dates with notifications, no reporting, and no integration with an issue tracker, so if you need those the Kanban board is the front end for a process you still have to build elsewhere. For a solo developer or a team that works asynchronously and commits often, the file format is a feature. For a team that needs to see who is blocked right now, it is not enough. The README's own TODO list, including a task to move all the user input to the beginning of the script and a create update script, also suggests an active project rather than a finished one.

Editorial conclusion

Adopt MarkdownTaskManager if you want a task board whose source of truth is a pair of Markdown files you can commit, diff and read in any editor. Skip it if your team needs concurrent editing, permissions or a real backend, since two people writing the same file will conflict. Before you rely on it, confirm your browser supports the File System Access API, because Firefox and Safari do not, and decide whether tasks belong in version control, where the README recommends versioning them.

Frequently asked questions

Official sources

1. ioniks/MarkdownTaskManager on GitHub
2. Issues
3. License: MPL-2.0
4. README
5. Releases