https://github.com/jjuchara/obsidian-tasks.nvim
Keyboard-first Obsidian task management for Neovim with multi-vault views and ordered tag trees
https://github.com/jjuchara/obsidian-tasks.nvim
lua neovim neovim-plugin obsidian productivity task-management
Last synced: 12 days ago
JSON representation
Keyboard-first Obsidian task management for Neovim with multi-vault views and ordered tag trees
- Host: GitHub
- URL: https://github.com/jjuchara/obsidian-tasks.nvim
- Owner: jjuchara
- License: mit
- Created: 2026-07-02T11:36:37.000Z (24 days ago)
- Default Branch: main
- Last Pushed: 2026-07-03T12:58:49.000Z (23 days ago)
- Last Synced: 2026-07-03T13:29:32.824Z (23 days ago)
- Topics: lua, neovim, neovim-plugin, obsidian, productivity, task-management
- Language: Lua
- Size: 32.2 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-neovim-sorted - jjuchara/obsidian-tasks.nvim - first Obsidian task management for Neovim with multi-vault views and ordered tag trees | (Note Taking)
- awesome-neovim - jjuchara/obsidian-tasks.nvim - Keyboard-first Obsidian task management across multiple vaults with ordered tag trees. (Note Taking / Cursorline)
README
A keyboard-first task cockpit for one or many Obsidian vaults.
Your Markdown stays the source of truth.
Install ·
Configure ·
Use ·
Roadmap
---
## Why obsidian-tasks.nvim?
Keep notes in Obsidian and stay in Neovim when it is time to execute. The plugin reads ordinary Markdown checkboxes, builds an ordered tag tree, and lets you complete or create tasks without introducing a database or rewriting your vault.
| | Capability |
|---|---|
| 🗂️ | Combine multiple vaults in one view or switch repositories with tabs inside the task view |
| 🌳 | Group tasks recursively by tag order: `#work #frontend #urgent` |
| ⚡ | Complete tasks with `` and append `✅ YYYY-MM-DD` automatically |
| ✍️ | Create tasks through a guided repository, tag, start date, and deadline flow |
| 🪟 | Use a centered floating window or a regular native split |
| 🔒 | Detect stale source lines before writing and update files atomically |
| 🧩 | Run on the built-in Neovim API with no required dependencies |
## Installation
### lazy.nvim
```lua
{
"jjuchara/obsidian-tasks.nvim",
opts = {
repositories = {
{
name = "personal",
alias = "Personal tasks",
path = "~/notes/personal/Tasks.md",
},
},
mappings = {
open = "to",
create = "ta",
},
},
}
```
### Native packages
```sh
git clone https://github.com/jjuchara/obsidian-tasks.nvim \
~/.local/share/nvim/site/pack/plugins/start/obsidian-tasks.nvim
```
Then call `setup()` from your configuration.
## Configuration
The only required option is `repositories`. A repository accepts either a direct `path` to a task file or a `vault` plus a relative `todo_file`. Its optional `alias` is used as the display label while `name` remains the repository identifier.
```lua
require("obsidian-tasks").setup({
repositories = {
{
name = "personal",
alias = "Personal tasks", -- optional display label
path = "~/notes/personal/Tasks.md",
},
{
name = "work",
vault = "~/notes/work",
todo_file = "Projects/Tasks.md",
},
},
view = {
type = "float", -- "float" or "window"
width = 0.5, -- fraction of editor width
height = 0.5, -- fraction of editor height
border = "rounded",
title = " Obsidian tasks ",
close_on_leave = true, -- close a float when focus leaves it
repository_mode = "sections", -- "sections" or "tabs"
window_command = "botright new",
status = "active", -- "active", "done", or "all"
sort = "source", -- "source", "deadline", or "title"
filter = nil, -- optional initial tag filter, e.g. "#work"
fold_level = 99, -- initially expand groups through this tag depth
},
dates = {
display_format = "%d.%m.%Y", -- strftime format used in the task view
},
creation = {
default_start_today = true,
prompt_additional_tags = true,
infinity_marker = "♾️",
},
completion = {
marker = "✅",
},
mappings = {
open = "to", -- global mapping, nil disables it
create = "ta", -- global mapping, nil disables it
create_in_view = "a",
toggle = "",
edit = "",
delete = "d",
undo = "u",
open_source = "gf",
refresh = "r",
close = { "q", "" },
cycle_status = "s",
cycle_sort = "o",
filter = "f",
next_repository = "",
previous_repository = "",
},
})
```
## Usage
### Commands
| Command | Action |
|---|---|
| `:ObsidianTasks` | Open the task view |
| `:ObsidianTasksCreate` | Start the guided creation flow |
| `:ObsidianTasksRefresh` | Reload every open task view |
| `:ObsidianTasksSort [source\|deadline\|title]` | Set sorting, or cycle it without an argument |
| `:ObsidianTasksFilter [#tag\|clear]` | Select or set a tag filter, or clear it |
### Task view
| Key | Action |
|---|---|
| `a` | Create a task without leaving the task view |
| `` | Toggle the task under the cursor |
| `` | Edit task text, tags, start date, and deadline |
| `d` | Delete the task under the cursor after confirmation |
| `u` | Undo the latest task operation |
| `gf` | Open the Markdown source at the task line |
| `s` | Cycle `active → done → all` |
| `o` | Cycle `source → deadline → title` sorting |
| `f` | Select a tag filter or clear the active filter |
| `za`, `zc`, `zo` | Toggle, close, or open the tag group under the cursor |
| `r` | Refresh from disk |
| `q`, `` | Close the view |
A floating view is modal by default: clicking another window closes it. Set `view.close_on_leave = false` if you prefer a persistent float.
Task-view mappings must be unique. For example, do not assign both `edit` and `open_source` to ``.
Tag filtering matches any tag on a task, remains active after refresh, and applies to every open task view.
Tag groups use native Neovim folds and expose a fold column for mouse interaction. Their expanded and collapsed states are preserved across refreshes, sorting, filtering, and repository navigation. Set `view.fold_level = 0` to start with top-level groups collapsed, or use a larger depth to reveal initial levels.
### Creating a task
1. Select a repository when more than one is configured.
2. Enter the task text.
3. Select or create the primary tag, press Space to choose the tag under the cursor, or press Enter immediately to continue without one.
4. Choose any number of additional tags from the existing-tag list. Press Enter to continue, or press Space to toggle the tag under the cursor. Selected additional tags are marked with `[x]`; use `+ new tag...` to add and select a new tag.
5. Confirm the start date and optional deadline. Enter `yesterday`, `today`, `tomorrow`, an ISO date such as `2026-07-10`, or a date matching `dates.display_format`. Leading zeroes are optional, so `7.3.2026` is accepted for `%d.%m.%Y`.
The completion notification shows the persisted tag path, for example `#work → #gantt`.
When task creation starts from an open task view, the view stays open and the newly created task is focused after refresh.
Dates are always stored as `YYYY-MM-DD`. `dates.display_format` changes rendered dates and the examples shown in creation prompts without modifying Markdown. Active tasks due today or tomorrow use `ObsidianTasksDueSoon`; overdue tasks use `ObsidianTasksOverdue`.
Deadline sorting adds virtual `#overdue`, `#due-soon`, and `#on-track` groups. `#due-soon` covers today and tomorrow; later deadlines, completed tasks, and tasks without deadlines are `#on-track`.
Editing a task from the task view rewrites the Markdown task line while preserving the checkbox state, creation date, and completion date. Clearing the deadline stores the configured no-deadline marker.
## Markdown format
```markdown
## #work
- [ ] Ship the release #work #frontend #urgent 📅 2026-07-10
- [x] Fix the regression #work #backend ✅ 2026-07-02
```
Tags are significant from left to right:
```text
#work
└── #frontend
└── #urgent
└── Ship the release
```
When a task has no inline tag, the nearest `## #tag` heading is used as a fallback. YAML frontmatter and fenced code blocks are ignored.
## Multiple repositories
`repository_mode = "sections"` renders all repositories in one buffer with repository headers. `repository_mode = "tabs"` shows repository tabs inside the task view and renders tasks from the active repository. Use `` / `` or click a tab to switch repositories.
## Development
Run the test suite without a plugin manager:
```sh
nvim --headless -u NONE -i NONE \
"+set rtp+=$PWD" \
"+luafile tests/run.lua" \
+qa
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow and `:help obsidian-tasks` for the built-in manual.
## Status
The core workflow is usable today. Advanced queries, recurrence, and live filesystem watching are tracked in [FUTURE.md](FUTURE.md).
## License
[MIT](LICENSE) © 2026 jjuchara