Documentation & Getting Started
A task-management system for individuals that stores data as markdown files (with YAML frontmatter) on disk while providing beautiful, purpose-built interfaces for actually managing your tasks. Tasks can be read and manipulated via text editors (Obsidian, VSCode), command line tools, and AI coding assistants.
The core idea: provide the right user interface in the right context.
| Tool | Description | Directory | Status |
|---|---|---|---|
| Specs | Formal specifications for the protocol | tdn-specs/ | ✅ Stable |
| CLI | Command-line interface for humans and AI agents | tdn-cli/ | ✅ Stable |
| Claude Plugin | Claude Code plugin for AI-assisted task management | tdn-claude-plugin/ | ✅ Stable |
| Desktop App | Cross-platform Tauri app for day-to-day use | tdn-desktop/ | ✅ Alpha (macOS) |
| Obsidian Plugin | Render task wikilinks as interactive widgets | obsidian-taskdn | ✅ Stable |
| Starter Vault | Pre-configured Obsidian vault with templates/bases | tdn-obsidian-starter-vault | ✅ Stable |
| Website | Documentation and marketing site | website/ | ✅ Stable |
- Project Overview & Philosophy – Why this project exists, design decisions. Read first.
- The Core Specification – Formal spec for task/project/area file formats.
Download the latest release from the website and configure the paths in the preferences.
brew tap dannysmith/taproom
brew install tdnSee tdn-cli/README.md for more options and usage.
The Claude Code plugin teaches Claude to work as a productivity assistant, using the tdn CLI to help manage tasks.
Install from marketplace:
/plugin marketplace add dannysmith/taskdn
/plugin install tdn@tdn-marketplace
Or load locally during development:
claude --plugin-dir ./tdn-claude-pluginThe Obsidian plugin renders wikilinks to task files as interactive checklist widgets. Click to toggle status, open files, or navigate to projects/areas.
See tdn-obsidian-plugin/README.md for installation instructions.
This is a monorepo. Each tdn-* directory is a self-contained project with its own documentation, tests, build configuration etc.
taskdn/
├── demo-vault/ # Sample vault for testing
├── docs/ # Project-wide documentation
│ ├── archive/ # Old docs for reference
│ ├── developer/ # Developer guides common to all products
│ ├── tasks-done/ # Completed development tasks
│ └── tasks-todo/ # Active development tasks
├── tdn-cli/ # CLI tool (TypeScript/Bun + Rust)
├── tdn-claude-plugin/ # Claude Code plugin
├── tdn-desktop/ # Desktop app (Tauri)
├── tdn-obsidian-plugin/ # Stub with README.md pointing at obsidian-taskdn repo
├── tdn-specs/ # Protocol specifications
└── website/ # Documentation & marketing site (Astro/Starlight)
Work which cuts across multiple products can happen in the top-level directory - this will usually be the case for early work on new products. Work which is tightly scoped to an individual product should happen in the project's own sub-directory. Each of these is set up to be an entirely independent project and each has its own README with setup instructions.
Run these from the repository root with bun <script>:
| Script | Description |
|---|---|
versions | Show local vs published versions for all products |
monorepo:check | Run lint, typecheck, and tests across all products |
cli:install-local | Install the CLI locally via symlink (for development) |
demo:reset | Reset the dummy test vault to a clean state |
demo:import-to-things | Import demo vault tasks into Things.app |
task:complete | Move a completed dev task to tasks-done |
task:rename-done | Add dates to existing completed task files |
See docs/developer/releases-and-versioning.md for release processes.
This monorepo uses different licenses for different components:
| Component | License | Rationale |
|---|---|---|
| tdn-specs | CC BY 4.0 | Maximum openness for spec adoption |
| tdn-desktop | AGPL-3.0 | Copyleft; modifications must be shared |
| tdn-cli | MIT | Permissive; maximum adoption |
| tdn-claude-plugin | MIT | Permissive; standard for plugins |
| website | MIT (code) / CC BY 4.0 (content) | Standard for docs |
| obsidian-taskdn | MIT | External repo |
| Everything else | MIT | Default |
See the root LICENSE file for full details.