Org in Helix

Helix knows the org language already; it only needs to be told to use the server. Helix has no plugins, so what org-lsp does comes as standard LSP: the commands are code actions (Space a), the agenda is a file Helix opens when the server asks, what a command asks for is picked from the code actions or typed as a rename, and there is no calendar. Helix has no semantic tokens either: the colors come from tree-sitter queries of org-lsp's, for Org files and for the agenda (Colors).

Installing#

curl -fsSL https://github.com/kristijanhusak/org-lsp/releases/download/nightly/install.sh | bash -s -- helix

or, in a checkout of this repository, scripts/install.sh helix (--release v0.2.0 for a release, --source for the server built from the checkout). The script puts the server from the nightly release in ~/.local/bin (ORG_LSP_BIN_DIR names another directory) and adds Org to ~/.config/helix/languages.toml, with the server's whole path, between two # BEGIN org-lsp and # END org-lsp comments that it replaces when run again; a file that sets up Org already is left as it is. It puts Org's colors in ~/.config/helix/runtime/queries/org and org-agenda, in place of what is there. Run it again to update.

By hand: put org-lsp on your PATH (cargo install --path server/org-lsp in a checkout), and add editors/helix/languages.toml to ~/.config/helix/languages.toml (or a project's .helix/languages.toml):

[language-server.org-lsp]
command = "org-lsp"

[language-server.org-lsp.config]
show_document = true
message_requests = false

[[language]]
name = "org"
file-types = ["org", "org_archive"]
language-servers = ["org-lsp"]

[[language]]
name = "org-agenda"
scope = "source.org-agenda"
grammar = "org"
language-id = "org"
file-types = [{ glob = "org-lsp-view-*/Agenda.org" }]
language-servers = ["org-lsp"]

and copy the queries of editors/helix/runtime/queries to ~/.config/helix/runtime/queries:

mkdir -p ~/.config/helix/runtime/queries
cp -R editors/helix/runtime/queries/org editors/helix/runtime/queries/org-agenda ~/.config/helix/runtime/queries/

The two options say what Helix does without telling the server: it opens the documents the server asks it to show (the agenda, a capture buffer, an entry's file), and it shows no list for a server, so the choices of a question come in the code actions instead. Without them there is no agenda and no capture. file-types opens archive files as Org too, with the server, as Emacs does. The second language is the agenda, which the server writes to Agenda.org in a directory of its own (org-lsp-view-… in the temporary directory): Org to the server (language-id) and to the grammar, with colors of its own.

Setting it up#

The server's options go in the config table under the server, which Helix passes to it as it is. Inlay hints show the indentation of files with org-indent-mode, the time clocked and the … of shrunk columns. With soft-wrap on, a line that wraps goes on under that indentation and its own, not under a headline's title or an item's text as in Org:

[editor.lsp]
display-inlay-hints = true

[language-server.org-lsp]
command = "org-lsp"

[language-server.org-lsp.config]
show_document = true
message_requests = false
org_agenda_files = ["~/org"]
org_todo_keywords = ["TODO(t)", "NEXT(n)", "WAIT(w@/!)", "|", "DONE(d!)", "CANCELLED(c@)"]
org_log_done = "time"
org_log_into_drawer = true

[[language-server.org-lsp.config.org_capture_templates]]
key = "t"
description = "Task"
target = ["file+headline", "~/org/inbox.org", "Tasks"]
template = "* TODO %?\n  %U"

The server also reads the shared configuration file, ~/.config/org-lsp/config.toml, which every editor shares; config goes on top of it. Options of your own go there when install.sh wrote the config table, since it writes its block again on an update. configuration.org has every option of the server with its default. The server reads its options when it starts: run :lsp-restart after a change.

Using it#

Space a (code_action) in an Org file lists the commands that apply at the cursor: the TODO state, the priority, the timestamp under the cursor, clocking, scheduling, tags, refiling, archiving, new headings, and the agenda (Agenda commands for the menu), the TODO list and capture. keys/helix.org lists them, and says how to put the menu on another key.

What a command asks for, Helix cannot ask itself, so the server says what it waits for in the status line:

Press key for agenda command: pick the answer from the code actions

a choice (a view of the agenda menu, a TODO state, a capture template, a refile target, yes or no): Space a again, and the choices are first in the menu, the key of each in brackets (List of all TODO entries [t]). Another command drops the question.

Schedule: answer with a rename at the cursor

text or a date (+2d, fri 10:00), typed as a rename: Space r, type the answer as the new name, Enter; - alone is an empty answer, the prompt's default. There is no calendar.

The agenda opens as a file, Agenda.org, in the window you are in, with the cursor on today. Its commands are code actions there too: on an entry's line the entry's first (its TODO state, dates, tags, clocking, archiving, marks for a bulk action), then the view's (later, earlier, today, the span, filters, log and entry text modes, the menu again). gd on a line goes to its entry; the buffer picker (Space b) or ga goes back to the agenda where its cursor was (:open puts it at the start). The server changes the agenda's buffer with edits, so Helix counts it as changed: close it with :buffer-close!, or leave with :quit-all! (or :write it, the same text).

Moving a subtree up or down with its code action leaves the cursor where it was in the text, not on the subtree as in Emacs: Helix applies the action's edit itself, and goes to no place a server names for it. Helix gives a code action no count either: pick it again.

Helix has no keys for a server, so the agenda's keys are the code actions' titles, and what needs to know where the cursor goes is left out: follow mode, going to the entry in another window, column view. A document the server shows without the focus opens in a split to the right, which takes the focus: C-w h goes back. Capture opens its buffer, CAPTURE-….org, in the window too; Capture: finish, abort and refile are its code actions, and the buffer stays open once the entry is filed (Helix closes no buffer for a server). Helix reads no file again that changes on disk, so the date prompt's calendar, which the server writes as the day moves, is not shown: dates are typed.

Colors#

Helix 25.07.1, its latest release, has no semantic tokens, nor has its development branch (September 2026): the capabilities it sends a server have no textDocument.semanticTokens, and no setting turns them on. So the colors the server sends the other editors do not reach it. In their place, the queries of org-lsp in queries/org/highlights.scm (with injections.scm for the code of source blocks) and queries/org-agenda/highlights.scm color Org files and the agenda from their text, with the grammar Helix has for Org (milisims/tree-sitter-org). Helix reads them in ~/.config/helix/runtime before its own, which colors little more than headlines, blocks and drawers.

They give what the server colors elsewhere a scope of Helix's themes. Each scope is named after what it colors, and a theme that has only the start of it colors it with that: diff.minus.todo as diff.minus, red in most themes, as a TODO keyword is in Emacs.

Headlines

markup.heading.1 to markup.heading.8 by level, which themes that color only markup.heading show alike; the text of a done headline comment.done, a subtree tagged ARCHIVE comment.archived, an inline task comment.inlinetask

Keywords, priorities, tags

diff.minus.todo and diff.plus.done, constant.numeric.priority, tag; statistics cookies constant.numeric.cookie, diff.plus.cookie when complete

Planning and timestamps

keyword.planning (SCHEDULED:, CLOCK: …), constant.numeric.timestamp for active timestamps, comment.timestamp for inactive ones

Drawers and keywords

function.drawer, variable.other.member.property; #+KEYWORD: comment.keyword, the title markup.heading.title, the author, date and subtitle string.info

Blocks

their lines comment.block, quote and verse blocks markup.quote, comment blocks comment, example blocks and LaTeX environments markup.raw.block; the code of source blocks in its language's colors

Lists and tables

markup.list, markup.list.unchecked and markup.list.checked, the term of a description markup.bold.term; table bars and rules punctuation.special.table

Text

markup.bold, markup.italic, markup.underline, markup.strikethrough, markup.raw.inline.verbatim, markup.raw.inline.code, fixed-width lines markup.raw.inline.fixed; links markup.link.url, footnotes markup.link.url.footnote, targets label.target, macros function.macro, entities constant.character.escape.entity, LaTeX markup.raw.inline.latex; comment for comments

The agenda

its title markup.heading.agenda, the days markup.heading.date, the weekend's markup.italic.weekend; the time grid comment.timegrid and the current time markup.bold.now; entries scheduled diff.plus.scheduled, scheduled earlier diff.delta.scheduled, with a deadline to come diff.delta.deadline, due or past diff.minus.deadline, done comment.done; keywords, priorities and tags as in Org files

A theme of one's own changes them, on top of another one:

# ~/.config/helix/themes/my-org.toml, with theme = "my-org" in config.toml
inherits = "onedark"
"markup.heading.1" = { fg = "#61afef", modifiers = ["bold"] }
"markup.heading.2" = "#e5c07b"
"diff.minus.todo" = { fg = "#e06c75", modifiers = ["bold"] }
"markup.italic.weekend" = { fg = "#61afef", modifiers = ["bold"] }

What the queries cannot know, they do not show:

• The grammar sees the words of a paragraph, not Org's objects: links, emphasis and timestamps are found from the word that opens them to the one that closes them, on one line, with their spaces left plain, and inline code (src_python{…}) is not in its language's colors.
• TODO keywords are the usual ones (TODO, NEXT, STARTED, WAIT, WAITING, HOLD, PROJ, SOMEDAY, INPROGRESS, and done DONE, CANCELLED, CANCELED, CANCEL, KILL, FIXED), not those of org_todo_keywords or #+TODO:: others go in the #any-of? lists of the queries. The faces of particular keywords, priorities and tags, and the options of how Org looks (org_fontify_done_headline, org_emphasis_alist …), are not followed.
• In the agenda, a line is told by its words, with the default leaders (Scheduled:, Sched. 2x:, Deadline:, In 3 d.:, 2 d. ago:) and the category first: other leaders and prefix formats are not colored. Today's date, the clocked entry's line and how near a deadline is beyond its leader are not in the text, and are not shown.
• Nothing is hidden (link brackets, emphasis markers, entities): Helix lets no server hide text.

What works#

✅ all that org-lsp does works there, ❓ some does not (the last column says what and why), ❌ none does, — nothing to support yet. Parity is the share of what Emacs Org does in that area that org-lsp does; parity.org lists both.

TESTING.org lists what to try by hand.