Editors and debugger
Each editor’s setup is in its README: VS Code, Neovim and Helix. The Zed extension is editors/zed. An editor formats on save with nomi fmt (Formatting), reports what nomi check reports (Checking) through the language server nomi-lsp, debugs through nomi dap (Debugging), and a coding agent asks the compiler through nomi mcp (Coding agents).
The language server
Section titled “The language server”nomi-lsp gives diagnostics, hover, go-to-definition, completion, rename and code actions. Its diagnostics are nomi check’s, including code the program reaches that type-checks but cannot be compiled to run yet, and it reports each todo and dbg as a warning.
Hover. On a keyword, hover shows the construct it starts, what it does there and a link to the page that teaches it, following the place it stands in: as in an import or a pattern, case as an expression or a pipe stage, the function a return leaves, the iteration a break leaves, what a pub publishes. Hover also states rules the text leaves implicit:
- an
ifwithoutelsesays it is a statement and when its branch runs; - a binding’s
elsesays when it runs and whether it must leave; - the
[or{of a collection literal says which collection it builds and what expected it; - a punned
name:shows both the field or parameter it labels and the binding it reads, and go to definition on it offers both targets; - a value that converts to a wider type (a
List<Maybe<Int>>where aList<Display>is expected) ends with what the conversion does at run time: one pass over a collection’s elements, one match of a Maybe, Result or enum, a rebuild field by field, or a wrapper around a function. A conversion that leaves the value as it is says nothing; - a typed literal (
Html"<p>${name}</p>") says what type it is, that it is not aString, what builds it and what each${}takes, and a hover on a slot’s expression ends with what that slot takes.
Quick fixes. They include:
- append
()to a pipe stage that names a function without calling it; - insert
thenbefore a lambda written as a pipe stage; - insert
|> Display.to_string()before a stage that takes aStringwhen the piped value implementsDisplay; - put
|> Iter.take(todo)before a terminal stage over an infinite iterator; - write a tuple read by number by its ordinal,
t.0ast.first; - name a struct literal’s values written without field names, in declaration order;
- add
else Noneto anifwithoutelsewhose branch is aMaybe, or write_ =before a branch’s value where a statement drops it; - write missing functions, fields and
casearms, each filled withtodo, so the result checks; - write a type parameter used once as a parameter’s type, under one bound, as an interface value (
fn label<T>(value: T) where T: Namedbecomesfn label(value: Named)), which the server reports as a hint.
Refactors. “Remove type annotation” is offered on a field or parameter whose default already has the written type (limit: Int = 10 becomes limit = 10), and “Add type annotation” writes the type a default gives (limit = 10 becomes limit: Int = 10). Neither is offered as a fix or run by fix-all.
Coding agents: nomi mcp
Section titled “Coding agents: nomi mcp”nomi mcp serves the Model Context Protocol on stdin and stdout, so a coding agent asks the compiler what an editor asks it. To add it to Claude Code:
claude mcp add nomi -- nomi mcpOther clients take the same command in their MCP settings, as a stdio server whose command is nomi and whose argument is mcp. The server starts in the client’s working directory, and a relative path in a tool’s arguments is read from there.
| Tool | Arguments | Returns |
|---|---|---|
check | path | nomi check --format json’s records, as lists: diagnostics (each with its span, hints and any fix), files and summary, plus ok. |
type_at | file, line, col | The hover text the language server shows there: a type, a signature, a doc comment. |
definition | file, line, col | The locations the name there is declared at. |
references | file, line, col | Every use of the name there, its declaration included. |
search_std | query, limit | The standard library’s public functions that match, each as a program calls it (String.split), with its signature and first doc paragraph. |
run_tests | path, line | nomi test --format json’s records: tests and summary, plus ok. |
format | source or file | The formatted text and whether it changed. It never writes the file. |
explain | code | What a diagnostic’s code means and how to fix it; with no code, the codes. |
A position is a 1-based line and a 1-based byte column, as check reports them, and a location is a file with a span in the same form. A tool that fails returns its error as text with isError set, for the agent to read.
A search_std query with -> is a signature, such as String, String -> List<String>. Its parameters match in any order, a parameter with a default may be left out, and a single capital letter stands for any type: List<T> -> Maybe<T> finds List.first, and so does List<Int> -> Maybe<Int>. A query type also matches an interface it implements, so List<T> -> Int finds Iter.count, whose parameter is an Iter<T>, and List<String> -> String finds String.join; a result matches the interface a query asks for. A refinement matches where its base is asked for, so List<T> -> Int finds Iter.count though it returns a NonNegativeInt. Exact matches come first, then generic ones, then ones through an impl or a refinement’s base. Any other query matches names and the text of doc comments.
check and run_tests run nomi check and nomi test as child processes of the same nomi, and download the modules a project needs as those commands do. The other tools run in process: the language server’s analysis for positions, which reads each file from the disk when a tool names it, and the formatter.
Debugging
Section titled “Debugging”nomi dap is a Debug Adapter Protocol server that editors start: VS Code’s extension, Neovim through nvim-dap, Zed’s extension and Helix’s :debug-start templates. It debugs a file’s main, its tests, or the one test --line would select, as nomi run and nomi test run them.
- Breakpoints. Line breakpoints (one on a line with no statement lands on the next statement), each with an optional condition, hit count (
5,>= 5,% 10) or log message with{expression}parts. Function breakpoints take a name as the call stack shows it (transact,Account.deposit,Display.to_stringfor every impl, or file-qualified), and stop at its first statement in every instance of a generic function. - Exception stops. A trap, a failed assertion and an
Errreturned frommainstop by default; an uncaught task failure, where it reaches theTask.awaitthat awaits it, can be turned on. - Stepping. Step over, into and out, step into target (pick one call on the line, lambdas passed to
Iteradapters included), pause, and restart frame. Stepping passes through the standard library unless the launch setsjustMyCodeto false. - Step back and reverse continue. Going back replays the program from its start, supplying input, the clock, randomness and files from what the session recorded, so nothing is printed or read twice. A program that starts a task, a
concurrentblock, a supervisor or a channel cannot go back, and says why. - Inspecting. The call stack shows a callback under the operation that called it (
main, thenIter.map, then the lambda) and marks a frame a tail call replaced. Each frame’s locals appear by their Nomi names, as a tree whose lists page. A struct’s children are its fields, and a tuple’s or a named tuple’s are its items by the names that read them,first,secondand on totwentieth; an item past the twentieth, which has no name, shows as[20], its index counted from zero. A Pipeline scope shows each stage of the|>chain the frame is in, and insideio.captureorio.replaya Captured output scope shows what the code printed into the capture. - Evaluating. Watches, hovers and the debug console evaluate Nomi in the selected frame. An expression with an effect (printing, files, the clock) is refused unless it ends with
// allow effects, and a hover never runs one. Each evaluation stops after 1,000,000 steps or 2 seconds. - Input and output. With
consoleset to"integratedTerminal"(the default for a program) the program reads and writes in the editor’s terminal; with"internalConsole"(the default for tests) its output goes to the debug console and it reads end of input.
A launch configuration takes mode ("run" or "test"), program, line, args, cwd, env, console, justMyCode and stopOnEntry; the VS Code README has the table.
Embedded files in the editor
Section titled “Embedded files in the editor”Hover on an embed declaration’s name, or on a use of it, shows its patterns, how many files and bytes it holds, and the first files with their sizes; hover on one pattern shows what that pattern matched. Go to definition on a pattern opens the file or folder it names, every match for a glob. A pattern that matches nothing, or that a rule refuses, is a diagnostic at the pattern: a warning when the path it names does not exist yet, an error otherwise. The server finds the files without reading them, and it rechecks the declaration when the declaring file changes, not when a file it embeds is added or removed.
Phrase catalogs in the editor
Section titled “Phrase catalogs in the editor”The language server reports a catalog’s errors in the catalog file, open or not, and rechecks when a catalog changes. Go to definition on a call of a phrase lands on its declaration, and go to implementations lists its catalog entries. Hover on a phrase shows its signature, its doc comment and its text in the source locale and in each listed and partial locale, naming the locale whose text a locale with no current translation shows. In a catalog it completes the file’s phrase names in a table’s header, the phrase’s parameters after $, and a variant’s keys: the plural categories the locale’s rules select for the selector, the enum’s variants, or the genders the module’s nouns have; in a noun’s entry, its gender and cases, the language’s genders as its gender, and the cases after case=. Hover on a noun shows its gender and forms in each locale, and go to implementations lists its catalog entries. Its quick fixes add a listed locale’s missing translation (the source text as source, and as text with every arm the locale needs), mark a stale translation current as nomi phrases accept does, add the plural, enum or gender arms a translation lacks, and add each form a noun lacks that the locale’s phrases ask for, a copy of its nominative. An editor attaches the server to the TOML files under [i18n].catalogs; the server serves no other TOML file.
The server colors the MessageFormat 2 in a phrase or noun body and in a catalog’s source, text and form strings with semantic tokens, since no editor ships an MF2 grammar: .input, .local and .match as keywords, $count as a parameter (a .local as a variable), :integer and the whole of :nomi:noun as functions, count= and case= as properties, keys such as one and * and name literals such as genitive as enum members, and the braces {{, }}, { and } as operators. The text between them keeps the string color. A body with a syntax error is colored up to the error. VS Code and Neovim show the tokens with no setting. Zed shows them only with semantic tokens on, "languages": { "Nomi": { "semantic_tokens": "combined" } } in its settings, and for catalogs the same under "TOML". Helix does not read semantic tokens, so a body there stays one string.
Hover works inside that MessageFormat 2 too, in a body and in a catalog alike. A $name shows the parameter with its type and comment, a noun’s $count what passes it, and a .local the expression it names. A function such as :integer or :nomi:noun shows what it writes, the types it takes, how it selects under .match and its options, and an option such as case= what it does, with the cases of the text’s locale. A variant key shows its plural category in the text’s locale (the source locale in a body, the catalog’s in a catalog) with example numbers, few in Polish being 2–4, 22–24, 32–34, …; an exact key such as 0 matches only that number; a gender key names the gender; and * lists the categories or genders it covers that no arm names. .input, .local and .match show one line each.
On a phrase whose text has no .match, the refactor “Add plural forms for $count” is offered for each Int parameter, and on a noun for its $count. It rewrites the text to select on the parameter, with an arm for each plural category the source locale’s rules give a whole number and the catch-all, each holding the old text for you to edit:
pub phrase cart_items(count: Int) ` .input {$count :integer} .match $count one {{{$count} items in your cart}} * {{{$count} items in your cart}} `
An existing .input {$count ...} stays. In a Polish project the arms are one, few, many and *. In a catalog the same refactor rewrites the translation or noun form under the cursor with that locale’s categories.