Awsum for Neovim

Neovim plugin for the Awsum programming language (.aww files).

Features

• Syntax highlighting (Tree-sitter)
• Code formatting (awsum format)
• Inline diagnostics (errors + warnings)
• Quick fixes (code actions)
• Document symbols (Structure view / breadcrumbs)
• Workspace symbol search

All of the above are powered by the awsum compiler's bundled language server — there is no separate awsum-lsp to install. As long as the awsum binary is on your PATH, the plugin will spawn it as awsum lsp and route every editor request through it.

Requirements

• Neovim 0.12+ (uses the built-in vim.lsp.config and vim.treesitter APIs).
• The awsum compiler on your PATH — see awsum-lang/awsum.
• A C compiler, to compile the bundled Tree-sitter parser once at install time:
  • macOS: xcode-select --install (Xcode Command Line Tools).
  • Linux: build-essential (Debian/Ubuntu) / base-devel (Arch) / equivalent.
  • Windows: run from a "Developer Command Prompt for VS" after installing Visual Studio Build Tools so MSVC cl.exe + link.exe are on PATH. MinGW gcc also works if available. Standalone LLVM Clang alone is not sufficient — it relies on link.exe from MSVC.

Install

The snippets below pin to v0.0.7. Replace it with the version of awsum you have installed — plugin and compiler must match (see Versioning).

The tree-sitter parser binary is compiled the first time you open a .aww file (~1 second, cached on disk afterward). You don't need to wire an install-time build hook — the plugin handles it automatically.

Option 1: vim.pack (built-in, no extra dependencies)

Neovim 0.12+ ships vim.pack as its built-in plugin manager. Add to ~/.config/nvim/init.lua:

vim.pack.add({
  { src = "https://github.com/awsum-lang/awsum-nvim", version = "v0.0.7" },
})

-- To update later:
--   :lua vim.pack.update({ 'awsum-nvim' })  -- opens a confirm tabpage
--   :w                                      -- (in the confirm buffer) applies
--   :restart                                -- reloads plugins with new code

-- To uninstall: remove the vim.pack.add call above, then:
--   :lua vim.pack.del({ 'awsum-nvim' })

Option 2: lazy.nvim

If you already use lazy.nvim, save the spec to ~/.config/nvim/lua/plugins/awsum.lua:

return {
  "awsum-lang/awsum-nvim",
  tag = "v0.0.7",
  ft = "aww",
}

-- To update later:
--   :Lazy update awsum-nvim   -- pulls the new tag, reloads the plugin

-- To uninstall: delete this spec file (or remove the entry from your inline
-- setup table), then :Lazy clean to remove the on-disk plugin directory.

If your config keeps plugin specs inline, drop the return and paste the table into your existing require("lazy").setup({ ... }) call instead.

Option 3: Manual

git clone --branch v0.0.7 https://github.com/awsum-lang/awsum-nvim \
  ~/.local/share/nvim/site/pack/awsum/start/awsum-nvim

To update later:

cd ~/.local/share/nvim/site/pack/awsum/start/awsum-nvim
git fetch --tags
git checkout vX.Y.Z   # the new tag matching your awsum

To uninstall:

rm -rf ~/.local/share/nvim/site/pack/awsum/start/awsum-nvim

Usage

Syntax highlighting and diagnostics activate automatically on .aww files. Other LSP features are invoked the standard Neovim way.

Formatting

One-shot, from inside Neovim:

:lua vim.lsp.buf.format()

Bind a keymap (in ~/.config/nvim/init.lua):

vim.keymap.set('n', '<leader>f', vim.lsp.buf.format, { desc = 'Format buffer' })

Format on save:

vim.api.nvim_create_autocmd('BufWritePre', {
  pattern = '*.aww',
  callback = function() vim.lsp.buf.format() end,
})

Diagnostics

Action	Default keymap (Neovim 0.10+)	Ex-command
Open diagnostic at cursor in floating window	<C-w>d	:lua vim.diagnostic.open_float()
Jump to next diagnostic	]d	:lua vim.diagnostic.goto_next()
Jump to previous diagnostic	[d	:lua vim.diagnostic.goto_prev()

Code actions, symbols

:lua vim.lsp.buf.code_action()
:lua vim.lsp.buf.document_symbol()
:lua vim.lsp.buf.workspace_symbol()

Bind to your own keymaps as you prefer.

Restart the LSP server

:AwsumRestartLspServer

Stops the awsum lsp process and starts a new one with the same settings. Useful after a local stack install of a new awsum build, or to clear any in-memory state on the server. No default keymap; bind via vim.keymap.set if you use it often.

Configuration

The plugin works with zero configuration. To override defaults, call setup with the fields you want to change:

require("awsum").setup({
  cmd = { "/custom/path/awsum", "lsp", "--stdio" },
  root_markers = { ".git", "awsum.json" },
})

With lazy.nvim, this is idiomatic via the opts field:

{
  "awsum-lang/awsum-nvim",
  tag = "v0.0.7",
  ft = "aww",
  opts = { cmd = { "/custom/path/awsum", "lsp", "--stdio" } },
}

Versioning

awsum-nvim A.B.C is built and tested against awsum A.B.C. Mismatched versions are not supported — at startup the language server compares the plugin's expected version against its own and shows a notification on mismatch.

Related

• Compiler (hosts awsum lsp): awsum-lang/awsum
• Tree-sitter grammar: awsum-lang/tree-sitter-awsum
• VSCode extension: awsum-lang/awsum-vscode
• Zed extension: awsum-lang/awsum-zed
• IntelliJ Platform plugin: awsum-lang/awsum-intellij
• Website: awsum-lang.org

AI use

This Neovim plugin is developed with substantial usage of generative AI. Every generated change is reviewed, edited, and accepted by a human before it lands in the repository, and no output is shipped unedited.

License

Apache 2.0 — see LICENSE and NOTICE.