A Claude Code skill for managing TaskNotes tasks in Obsidian from the command line. Create, query, update, and track tasks without leaving your terminal.
The skill is a thin Python orchestrator that routes commands to the best available tool:
| Tool | Mode | When Used |
|---|---|---|
| mtn (mdbase-tasknotes) | File-direct | Default. Reads/writes task markdown files directly. Works offline. |
| tn (tasknotes-cli) | HTTP API | When Obsidian is running with the API enabled. Adds pomodoro, calendars, recurring tasks. |
| Obsidian CLI | Obsidian | Quick property reads/writes and vault-wide search. |
| Direct HTTP API | HTTP | Fallback when CLIs are unavailable but the API is reachable. |
Both mtn and tn are maintained by the TaskNotes plugin author and read/write identical task files.
- Obsidian with the TaskNotes plugin installed
- Bases core plugin enabled
- Claude Code CLI
- Node.js 14+ and uv (Python runner)
git clone https://github.com/pickleton89/obsidian-tasknotes-skill.git
cd obsidian-tasknotes-skillThe install command copies the skill files (SKILL.md, scripts, references) into your vault's .claude/skills/ directory. No symlinks -- all files are copied for Obsidian sync compatibility.
uv run python scripts/tn_manager.py --vault /path/to/your/vault installuv run python scripts/tn_manager.py --vault /path/to/your/vault setupThis installs mtn (npm global) and tn (git clone + npm link), then configures both to point at your vault.
In Obsidian, go to Settings -> TaskNotes -> Integrations and enable:
- Enable mdbase spec -- required for
mtn(file mode) - Enable HTTP API -- required for
tn(API mode)
Pull the latest version and re-install into your vault:
cd /path/to/obsidian-tasknotes-skill
git pull
uv run python scripts/tn_manager.py --vault /path/to/your/vault installTo check whether an update is available:
uv run python scripts/tn_manager.py --vault /path/to/your/vault check-updateThe install command is idempotent -- it overwrites the previous installation with the latest files.
In Claude Code, invoke the skill with /tn:
/tn status # Task overview
/tn create "Design landing page" --priority high --due 2026-04-15
/tn nlp "Buy groceries tomorrow @home #errands ~30m"
/tn list --overdue
/tn complete "Design landing page"
Or run the orchestrator directly:
uv run python scripts/tn_manager.py --vault /path/to/vault <command> [options]| Command | Description |
|---|---|
status | Task counts by status, overdue, today's schedule |
create "Title" [opts] | Create a new task |
nlp "natural language" | Create task from natural language |
update "Title" [opts] | Update an existing task |
complete "Title" | Mark task as completed |
delete "Title" [--force] | Delete a task |
list [filters] | List and filter tasks |
search "query" | Search tasks by content |
today | Tasks due or scheduled today |
overdue | Overdue incomplete tasks |
start-timer "Title" | Start time tracking |
stop-timer | Stop time tracking |
timer-log [--period P] | Show time tracking log |
projects [list|show] | Project overview |
pomodoro [start|stop|status] | Pomodoro timer (API-only) |
install [--source PATH] | Install/update skill into vault |
check-update | Check if installed skill is outdated |
setup | Install/configure CLI tools |
help | Show all commands and options |
--vault PATH Obsidian vault path
--status VALUE Task status (open, in-progress, done)
--priority VALUE Priority (low, normal, high)
--due YYYY-MM-DD Due date
--scheduled YYYY-MM-DD Scheduled date
--tags "a,b" Comma-separated tags
--contexts "a,b" Comma-separated contexts
--projects "a,b" Comma-separated projects
--json Machine-readable JSON output
--file-only Force file mode (skip API)
# By property
uv run python scripts/tn_manager.py list --status in-progress --priority high
# Advanced expression (mtn)
uv run python scripts/tn_manager.py list --where 'due < "2026-04-01" && priority == "high"'# Advanced filter (tn)
uv run python scripts/tn_manager.py list --where 'priority:high AND tags:urgent'Both mtn and tn parse natural language with dates, priorities, tags, contexts, projects, and time estimates:
uv run python scripts/tn_manager.py nlp "Call dentist friday high priority @phone #health ~15m"obsidian-tasknotes-skill/
├── SKILL.md # Skill definition for Claude Code
├── scripts/
│ ├── common.py # Vault discovery, tool detection, API client
│ └── tn_manager.py # CLI orchestrator (routes to mtn/tn/API)
├── references/
│ ├── frontmatter-spec.md # TaskNotes YAML field reference
│ └── api-reference.md # HTTP API + CLI command reference
├── documentation/
│ └── TaskNotes-Documentation.md # Full plugin documentation
└── README_tasknotes.md # TaskNotes plugin README (reference)
When installed into a vault, only SKILL.md, scripts/, and references/ are copied to .claude/skills/obsidian-tasknotes/.
TaskNotes stores each task as a markdown file with YAML frontmatter:
---
tags:
- tasktitle: Review quarterly reportstatus: in-progresspriority: highdue: 2025-01-15contexts:
- "@office"projects:
- "[[Q1 Planning]]"
---
## NotesKey points to review...Tasks are identified by the #task tag (configurable). All property names are configurable via field mapping in the plugin settings. The skill reads these mappings at runtime.
- TaskNotes plugin -- the Obsidian plugin
- tasknotes-cli -- official CLI (API mode)
- mdbase-tasknotes -- official CLI (file mode)
- TaskNotes docs -- full plugin documentation
MIT