Skip to content

README.md

Latest commit

 

History

History
204 lines (151 loc) · 6.8 KB

README.md

File metadata and controls

204 lines (151 loc) · 6.8 KB

obsidian-tasknotes-skill

A Claude Code skill for managing TaskNotes tasks in Obsidian from the command line. Create, query, update, and track tasks without leaving your terminal.

How It Works

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.

Prerequisites

Installation

1. Clone the repo

git clone https://github.com/pickleton89/obsidian-tasknotes-skill.git
cd obsidian-tasknotes-skill

2. Install into your Obsidian vault

The 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 install

3. Install and configure the CLI tools

uv run python scripts/tn_manager.py --vault /path/to/your/vault setup

This installs mtn (npm global) and tn (git clone + npm link), then configures both to point at your vault.

4. Enable required plugin settings

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)

Updating

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 install

To check whether an update is available:

uv run python scripts/tn_manager.py --vault /path/to/your/vault check-update

The install command is idempotent -- it overwrites the previous installation with the latest files.

Usage

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]

Commands

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

Common 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)

Filtering

# 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'

Natural Language

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"

Project Structure

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/.

How Tasks Work

TaskNotes stores each task as a markdown file with YAML frontmatter:

---
tags:
  - task
title: Review quarterly report
status: in-progress
priority: high
due: 2025-01-15
contexts:
  - "@office"
projects:
  - "[[Q1 Planning]]"
---

## Notes
Key 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.

Related Projects

License

MIT