Obsidian-pm flips the usual project management software model on its head by using your plain Markdown files inside an Obsidian vault as the single source of truth. Instead of locking you into a database or external API, it reads and writes tasks and projects as Markdown files with YAML frontmatter metadata. This means your data stays fully portable, version-controllable, and sync-agnostic — a rare approach for a project management tool.
What obsidian-pm does and how it is built
At its core, obsidian-pm is an Obsidian plugin written in TypeScript that turns a vault into a full-fledged project management system. It stores tasks and projects in a configurable folder as plain Markdown files, each starting with YAML frontmatter containing task metadata like dates, dependencies, custom fields, and status.
The plugin offers three interchangeable views over the same underlying Markdown data: Table, Gantt, and Kanban. This lets you visualize and manage your projects in the format that suits your workflow best without duplicating or converting data.
The underlying architecture is built around reading these Markdown files, parsing the YAML frontmatter, and constructing an in-memory task graph to support features like dependency tracking and cycle detection. This graph enables smart rescheduling — if one task’s date shifts, the plugin propagates the change through dependent tasks automatically.
Because everything is stored as files, collaboration works through any sync mechanism you prefer — Git, Obsidian Sync, Syncthing, or even manual copy. Conflict resolution happens at the file level, so there’s no central server or API required.
Why the dependency engine and file-based model stand out
Most project management tools rely on databases or APIs to maintain state, dependencies, and scheduling. obsidian-pm eschews that entirely in favor of file-based storage. This approach has both advantages and tradeoffs.
The heart of the plugin is its dependency resolution engine. It builds a task dependency graph dynamically by reading YAML frontmatter from Markdown files. This graph not only detects cycles to prevent invalid task chains but also allows automatic propagation of date shifts through blocking and dependent tasks.
Under the hood, this means reading and parsing files on demand, without a dedicated database or backend service. The tradeoff is that file I/O and YAML parsing can be slower than querying a database, especially in large vaults. However, the plugin appears optimized to handle this efficiently, and the benefit is zero dependencies and maximum data ownership.
The plugin supports subtasks, recurring tasks, time logging, custom fields, and bulk operations, all while keeping the data human-readable and editable outside the plugin if needed. This is a rare balance — most tools either lock data into opaque databases or export/import formats that add friction.
On the code quality front, the project is TypeScript-based, which improves maintainability and reduces runtime errors. The modular design separating the data model, views, and dependency logic suggests a clean architecture that should be approachable for contributors or those wanting to extend the plugin.
Installation and quick start
Installation
Via BRAT (beta releases)
- Install the BRAT plugin from the community store.
- Open BRAT settings > Add Beta Plugin.
- Enter:
https://github.com/StepanKropachev/obsidian-pm - Enable the plugin in Settings > Community plugins.
Manual
- Download
main.js,manifest.json, andstyles.cssfrom the latest release. - Create a folder:
/.obsidian/plugins/project-manager/ - Copy the three files into that folder.
- Reload Obsidian and enable the plugin under Settings > Community plugins.
Quick start
- Click the dashboard icon in the ribbon (or run Open projects pane from the command palette).
- Click New project to create your first project. Give it a name, color, and icon.
- Open the project — it opens in Table view by default.
- Press + Add task to create your first task.
- Switch views using the Table / Gantt / Kanban tabs at the top.
Commands:
| Command | What it does |
|---|---|
| Open projects pane | Open the project list |
| Create new project | Open the new project modal |
| Create new task | Pick a project, then create a task |
| Create new subtask | Pick a project and a parent task |
| Import notes as tasks | Convert Markdown notes into tasks |
| Open current file as project | Open the active note as a project (needs pm-project: true) |
| Undo last action | Revert the last change |
| Redo last action | Reapply an undone change |
verdict
obsidian-pm is a strong choice if you want a project management system that keeps your data fully in Markdown files and integrates tightly with Obsidian. Its file-based approach means you avoid vendor lock-in and can collaborate through any sync mechanism you trust.
The dependency graph and cycle detection features are sophisticated for a plugin, enabling automated scheduling adjustments without a database backend. However, this architecture may hit performance limits with very large vaults or highly complex projects since it relies on file reads and YAML parsing.
If you value data portability, transparency, and multi-view project management inside Obsidian without introducing external dependencies, obsidian-pm is worth exploring. It’s less suitable if you need a centralized cloud service, real-time multiuser editing beyond file-level sync, or extremely large-scale project management.
Overall, the code is clean and well-structured for a plugin, making it a good example of how to build complex stateful apps on top of Markdown files in a modern TypeScript environment.
Related Articles
- Vaultwarden: a resource-efficient Rust implementation of the Bitwarden server API — Vaultwarden is a lightweight, Rust-based server compatible with the Bitwarden API, optimized for self-hosting with low r
- Inside Automattic’s VIP Go MU-Plugins: Modular WordPress Core Extensions with Modern Testing — Explore Automattic’s VIP Go MU-Plugins repo: modular WordPress core extensions with PHPUnit and Playwright tests, design
- nh: a Rust-based unified CLI for the Nix ecosystem with enhanced search and ergonomics — nh is a Rust CLI tool consolidating Nix, NixOS, and Home Manager commands with improved ergonomics, speed, and Elasticse
- awesome-copilot: modular community plugins and agentic workflows for GitHub Copilot — awesome-copilot is a community-curated collection of plugins and agents that extend GitHub Copilot with modular, agentic
- Jan: a local-first desktop app for large language models with Tauri and Rust — Jan is an open-source desktop app that runs large language models locally using Tauri, Node.js, and Rust. It offers priv
→ GitHub Repo: StepanKropachev/obsidian-pm ⭐ 281 · TypeScript