nvim-orgmode: an Org mode clone in Lua for Neovim 0.11.0+

What nvim-orgmode solves, and for whom

Org mode is a plain text format with a large amount of behaviour layered on top of it: TODO keywords, DEADLINE and SCHEDULED timestamps, tags, properties, archiving, clocking and an agenda that collects entries from many files. Emacs ships all of that. If you edit .org files in Neovim, you get syntax highlighting and nothing else, which means the agenda has no way to know that a deadline exists three files away.

nvim-orgmode fills that gap. It is described as an Orgmode clone written in Lua for Neovim, and the README lists what it covers: agenda views, search by tags and keyword, clocking, repeatable dates and ranges, capture to a default notes file, archiving to a file or via an ARCHIVE tag, and a set of file mappings for promoting headlines, changing TODO state, editing dates, refiling and toggling checkboxes. The audience is narrow and specific: people who have already decided that .org is their format and that Neovim is their editor, and who want the agenda to work without opening Emacs.

It is not a general note-taking app. The files stay plain text, and nothing about the format changes because the plugin is present.

How the plugin is put together

The repository layout tells most of the story. There is a lua/ directory for the plugin logic, a queries/ directory and a parser/ directory for tree-sitter, an lsp/ directory, plus ftplugin/, indent/ and syntax/ for the classic Vim-side filetype support. Parsing is therefore not a hand-written line scanner: the plugin depends on a tree-sitter parser for org, and the README credits a contributor for writing it.

The data flow is file-first. Agenda files are declared up front as a glob, the plugin reads those files, and the agenda, tag match, TODO list and search commands all query that parsed set rather than a database. Timestamps are interpreted, not stored: the README documents DEADLINE warning settings such as <2021-06-11 Fri 11:00 -1d>, SCHEDULED delay settings, three repeater types (+1w, ++1w, .+1w), and both time ranges and date ranges. That parsing layer is where most of the compatibility work lives, and it is the part most likely to disagree with Emacs on an unusual timestamp.

The lsp/ directory and the vim.lsp.enable('org') line in the Quickstart point at an experimental language server for org files. Treat it as a separate, less settled surface than the agenda, which is the part the README demonstrates with screenshots.

Installing nvim-orgmode and capturing your first task

The Quickstart uses Neovim's built-in package manager, so no external plugin manager is required. The README shows a single vim.pack.add call followed by the setup table, which is where the two required options live: org_agenda_files, a glob pointing at your org files, and org_default_notes_file, the file that capture writes to by default.

vim.pack.add({ 'https://github.com/nvim-orgmode/orgmode' })

-- Setup orgmode
require('orgmode').setup({
  org_agenda_files = '~/orgfiles/**/*',
  org_default_notes_file = '~/orgfiles/refile.org',
})

-- Experimental LSP support
vim.lsp.enable('org')

After restarting, the README gives two entry points: <Leader>oa opens the agenda prompt and <Leader>oc opens the capture prompt. Inside any orgmode buffer, g? lists the available mappings. If the agenda comes back empty, the first thing to check is that org_agenda_files actually matches the directory you keep files in, because the example path is a placeholder for ~/orgfiles and nothing is created for you. The README also points at docs/installation.org for other installation options, and the plugin can render its own documentation in an org buffer via :Org help, with the Vim help file at :help orgmode.txt.

Where the clone stops short of Org mode

The README is unusually direct about scope. A quoted note states that none of the Emacs Orgmode plugins will be built into nvim-orgmode, and that anything which is a separate plugin in Emacs Org mode should be a separate plugin here. The stated goal is to provide the functionality built into Emacs Org mode core, plus a foundation for external plugins. Read that as a boundary, not a roadmap promise: if your workflow depends on an Emacs Org mode extension, the plugin is not claiming to replace it.

Export is the clearest practical limitation. The feature list says exporting happens via emacs, via pandoc, or through custom export options. That means the plugin shells out to an external program for document conversion; it does not ship its own exporter. If neither Emacs nor pandoc is installed, export has nothing to call, and the README does not document a built-in fallback.

Notifications are marked experimental and tied to an open issue, so that feature should not be treated as settled. The language server is likewise labelled experimental in the Quickstart snippet. There is also a version mismatch worth noticing before you install: the repository description says Neovim 0.11.0+, while the Quickstart requirements section says Neovim 0.12.0 or later. Check which one your build satisfies rather than assuming the lower number is fine.

nvim-orgmode compared with Emacs Org mode and Neorg

The obvious alternative is Emacs itself. Emacs Org mode is the reference implementation: the agenda, the export backends, Babel for executing code blocks, and the extension ecosystem all live there. nvim-orgmode reimplements a subset of that core in Lua and inherits the parts it does not implement by calling out to emacs or pandoc. The difference in approach is architectural, not cosmetic. Emacs Org mode owns the whole pipeline from parse to export; nvim-orgmode owns the parse and the interactive commands, and delegates document conversion.

Neorg is a different kind of alternative. It is a Neovim plugin with its own file format and its own module system, rather than a reader for the .org format. Choosing it means your existing .org files are not the input, and the Org mode timestamp and agenda semantics do not carry over. That is the real trade-off: nvim-orgmode keeps your files compatible with Emacs and with anything else that reads org syntax, while a format of its own would give the plugin more freedom to design around Neovim. The README's choice to stay on the org format is the reason the plugin is worth considering at all for someone with an existing file collection.

If the deciding factor is export fidelity rather than editing, the external-tool dependency means the comparison is really between your installed pandoc or Emacs and the plugin, not between two Neovim plugins.

Maintenance, licence and upgrade cost

The last push to master was on 2026-09-21, two days before this writing, and the repository is not archived. Recent tagged releases are 0.7.5 and 0.7.4, both dated 2026-06-18, and 0.7.3 from 2026-05-05. The gap between the June tags and the September push suggests work on master that has not been cut into a release yet, so anyone tracking tags is a few months behind the branch.

Upgrading has a structural cost that comes from the version requirement rather than from the plugin's internals. The stated floor is Neovim 0.12.0 in the Quickstart, and the install path uses vim.pack.add, which is the built-in package manager. Both mean an upgrade of the plugin can be gated on an upgrade of Neovim itself. Plan for that rather than expecting the plugin to track an older editor indefinitely.

Development tooling is documented in the repository: make test runs the suite through a headless Neovim with tests/test.lua, make lint checks formatting with stylua, and make format rewrites it. There is a setup_dev target that installs a pre-commit hook from scripts/pre-commit-hook.sh. That matters if you intend to patch behaviour locally, because it tells you exactly how a change is expected to be validated before it lands.

The licence is MIT, which is permissive and imposes no copyleft obligation on your configuration or your notes. That is a statement about the licence identifier in the repository, not legal advice; if you redistribute the plugin, read the LICENSE file yourself.

Editorial conclusion

Adopt nvim-orgmode if you already keep .org files and want agenda, capture and refile inside Neovim without leaving for Emacs; skip it if you depend on Org Babel execution, org-export backends, or the Emacs extension ecosystem, since the README states that separate Emacs Org mode plugins stay separate here. Before committing, verify three things on your own machine: that your Neovim satisfies the stated 0.12.0 requirement in the Quickstart, that org_agenda_files matches where your files actually live, and whether :Org help and :help orgmode.txt cover the workflow you need. Export is the sharpest edge, because the README routes it through emacs or pandoc as external programs.

Frequently asked questions

Official sources

1. License: MIT
2. nvim-orgmode/orgmode on GitHub
3. Project website
4. README
5. Releases