org.nvim

Emacs Org mode, rebuilt for Neovim in pure Lua.

Outlines · TODOs · Agenda · Capture · Clocking · Spreadsheet tables · Babel · Export

Install · Tour · Features · Docs · Guide · Try it in your browser · Migrating from nvim-orgmode · FAQ · Changelog · Contributing

Org mode is one of the most loved tools in Emacs. It works as a plain-text outliner, planner, time tracker, spreadsheet, literate-programming notebook and publishing system. org.nvim puts all of that in Neovim. It isn't a syntax file with a few keymaps on top. It reimplements Org's behaviour: the agenda, capture templates, repeaters, clock tables, table formulas, Babel and export.

• 🪶 No dependencies. It's about 170k lines of Lua and needs no tree-sitter parser, external binary or companion plugin.
• 🔁 Works with Emacs. It reads and writes the same plain-text format, so you can edit a file in Emacs today and in Neovim tomorrow.
• ⌨️ Keys that fit Vim. Context-aware keys fall back to normal Vim behaviour when they don't apply (>> still indents, <C-a> still increments). Press g? in an org or agenda buffer to see what's available.
• 💤 Ready for LazyVim. It comes with which-key groups, a blink.cmp source, pickers for snacks.nvim, fzf-lua, Telescope and mini.pick, and a lualine clock, and it works with any other setup too.
• ✅ Tested. The headless test suite runs 4,800+ tests from 240+ spec files.

How does it compare with nvim-orgmode and Neorg? See why another Org plugin?.

Switching from nvim-orgmode? Migrating from nvim-orgmode (:h org-migrate) maps its options and keys to org.nvim's, and :Org migrate_config converts your setup.

On AI: org.nvim is written with AI assistance (Claude Code). To keep that honest, its behaviour is checked against the Emacs Org source rather than guessed, every feature comes with headless tests, and I review and use every change myself. Bug reports are very welcome, especially where it doesn't match Emacs.

With lazy.nvim / LazyVim:

-- ~/.config/nvim/lua/plugins/org.lua
return {
  "xheisenbugx/org.nvim",
  main = "org",
  lazy = false, -- startup cost is small: heavy modules load on first use
  opts = {
    org_directory = "~/org",
    agenda_files = { "~/org/**/*.org" },
    default_notes_file = "~/org/refile.org",
  },
}

Not using lazy.nvim? The guide covers vim.pack, rocks.nvim (:Rocks install org.nvim), plain Vim packages, a local checkout and blink.cmp completion. Neovim 0.11+ on Linux, macOS or Windows is all it needs; pandoc, LaTeX and Babel's interpreters are optional (requirements).

Restart Neovim and run :checkhealth org. New to Org? Run :Org tutor: it lists the lessons of a guided course, like vimtutor, each in a copy of its own where every org key works and each exercise gets a ✓ once you have done it (:Org tutor basics starts with the first; :h org-tutor). Not installed yet? Try it in your browser: the playground plays every lesson in a real Neovim, exercise by exercise, with captions and a follow-along mode where you press the keys.

For a longer tour, examples/tutorial.org has exercises for every feature and examples/00-index.org a file per area; nvim -u examples/minimal_init.lua examples/tutorial.org opens it without touching your config or your notes.

1. mkdir ~/org and open ~/org/todo.org.
2. Type * TODO Buy milk, press <Esc>, then <leader>os and <CR> to schedule it for today.
3. <leader>oa → a opens the weekly agenda. t changes the state of the entry under the cursor, and <CR> jumps to it.
4. <leader>oc → t captures a new task from anywhere. Finish with <C-c><C-c> or :w.
5. Press g? in any org or agenda buffer to list its keymaps.

Recorded in a plain Neovim with only org.nvim installed, from the tapes in docs/media/tapes (config: docs/media/demo/init.lua). The box in the bottom-right corner shows the key being pressed.

TAB / S-TAB cycle a subtree / the file like Emacs, M-k / M-j move a subtree, M-RET adds a heading at the right level, M-h / M-l promote and demote, <leader>ohs sorts and <leader>ohn narrows.

Ticking a checkbox updates the [2/4] and [50%] cookies of its parents; marking a task DONE can log a CLOSED: timestamp. Set the state with cit or <leader>oS, the priority with <leader>o,.

S-Right / S-Left cycle the bullet style, M-RET / M-S-RET add an item or a checkbox item, M-Up / M-Down move an item and renumber, and <leader>o- turns plain lines into a list.

<leader>ot opens fast tag selection with mutually exclusive groups, <leader>oxe sets the effort and <leader>op any property.

<leader>os / <leader>od open a floating calendar where you can type fri 14:00, +2w or w39; S-Right, <C-a> and <C-x> change a date in place, and <CR> on it opens that day's agenda.

<leader>oa → a opens the week (or the day): a time grid, a current-time line, deadline countdowns, overdue items and habit graphs, as in Emacs. Change states, reschedule, clock in, refile, filter and run bulk actions from it.

The dispatcher has the other Emacs views too: every TODO (t), a tags/property match (m) and a word search (s).

<leader>oc in any buffer, pick a template, type, and finish with <C-c><C-c> or :w. It's filed under a headline, an outline path or a date tree (templates).

<leader>or moves a subtree under another heading; <leader>o$ archives it to <file>_archive with its context in ARCHIVE_* properties.

Tables align themselves, and #+TBLFM formulas run on a Calc-compatible evaluator. Rows and columns can be inserted, moved and deleted with the formulas rewritten to follow, sorted and transposed.

<C-c><C-c> on a source block runs it asynchronously and writes the output back: Python, shell, Lua, Node, Ruby, R, Go, SQLite and more, with :var, :noweb, :cache, #+CALL, :session REPLs and tangling. <leader>o' edits a block in its own buffer with the language's filetype.

<leader>oxi clocks in (the statusline shows the total against the effort), <leader>oxr inserts a clock table that matches Emacs, and <leader>oC opens column view.

<leader>oxv shows image links as images and <leader>oxl renders LaTeX fragments, with Neovim 0.13's vim.ui.img in kitty, Ghostty or WezTerm, or snacks.nvim / image.nvim elsewhere (where previews work).

<leader>o. (C-c C-j) jumps to a heading of the file, <leader>og to any heading of your agenda files, through your picker of choice (pickers).

Relative timers for meeting notes (<C-c><C-x>0, <C-c><C-x>-), a countdown for the current entry (<C-c><C-x>;), and reminders before timed agenda entries with notifications.enabled.

<leader>oif inserts a footnote, :Org lint lists a file's problems in the location list, and with use_speed_commands = true single letters at the start of a heading run commands, like Emacs's speed keys.

<leader>ols stores a link, <leader>oli inserts it, <CR> follows it. <leader>o/ folds the file down to TODOs, a regexp, a tag match or deadlines.

<leader>oe opens the export dispatcher: HTML, LaTeX, Beamer, KOMA letter, man page, Markdown, ASCII, Org, iCalendar, ODT and Texinfo are ports of Emacs's back-ends, pandoc handles DOCX and EPUB, and :Org preview shows a live HTML preview.

The cli extension's org mcp is an MCP server: Claude Code, Claude Desktop and other MCP clients can read your agenda, find and show entries, capture, add headings, mark tasks done, reschedule, refile and clock in, with your own templates and keywords, through the same code as the editor. Results are compact JSON with a ready-to-use target for every heading, and /mcp__org__plan_day, weekly_review and triage_inbox come as prompts. --read-only keeps it to reading.

claude mcp add org -- org mcp

Press g? in any org or agenda buffer to list every keymap there, grouped by topic, with each command's Vim and Emacs keys on one row.

• The guide: installation in detail, every default key, configuration, capture templates, custom agenda commands, integrations, the Lua API, the differences from Emacs, every extension and the roadmap.
• The manual: :h org.nvim (doc/org.txt); every option is under :h org-config.
• The documentation website: the manual, the guide, the examples and the parity scorecard, searchable.
• FAQ (:h org-faq) and Migrating from nvim-orgmode (:h org-migrate, with :Org migrate_config to convert your setup).

98.6% of Org 9.8.12's commands, options, Babel languages, link types and export transcoders behave the same in org.nvim (strict count, October 2026). Emacs itself lists every one of them in Org 9.8.12; each is classified in docs/parity/inventory.tsv and scored by docs/parity/score.sh:

By area (strict):

Known gaps. This counts commands, options, Babel languages, link types and export transcoders, not every edge case of each, so it measures coverage rather than bug-for-bug equality. Where org.nvim differs from Emacs on purpose (prefix arguments are counts, the cursor sits on a character rather than between two), it is listed in the known differences from Emacs (:h org-differences). The status and note of every command and option are in the parity scorecard and docs/parity/inventory.tsv. If something behaves differently and isn't listed, please open an issue.

Method. A command or option counts as done only when org.nvim behaves equivalently and a spec exercises it; output that Emacs produces (buffer text, export, agenda lines) is compared with Emacs run in batch mode. Partial ones count half, and Emacs internals (byte compilation, caches, obsolete aliases) are left out. The full method, and how the numbers changed from round to round, are in the parity review.

Optional features modelled on popular third-party Emacs Org packages ship with org.nvim but stay unloaded until you enable them in extensions:

require("org").setup({
  extensions = {
    present = true,                  -- enable with the defaults
    roam = { directory = "~/roam" }, -- options are merged over its defaults
  },
})

Each one is ✅ stable (used daily, well covered by specs; changes to its options or keys are called out in the release notes) or 🧪 experimental (works and is tested, but its options may still change):

The guide describes each one with a demo, the extensions status page shows how close each experimental one is to stable, and :h org-extensions has every option.

Contributions of all sizes are welcome: bug reports, docs fixes, new link types, Babel languages, exporters, or anything on the roadmap. Each piece of Org lives in its own small module, and there's a fast headless test suite, so it's easy to get started:

git clone https://github.com/xheisenbugx/org.nvim && cd org.nvim
make test                                 # run all specs headlessly
make test SPEC=tests/spec/agenda_spec.lua # one spec
make lint                                 # stylua --check + source lint rules
make bench                                # time the first open and a 50,000-headline agenda

CONTRIBUTING.md explains how the code is organised and how to add a feature. CHANGELOG.md lists what changed in each release.

org.nvim is released under the MIT License.