Koja for VS Code

A VS Code extension for the Koja programming language. Works in VS Code and compatible editors (Cursor, VSCodium, Windsurf).

Getting started

1. Install the language server. The extension looks up koja and koja-lsp on your $PATH.

Installed Koja with asdf? You already have both. Every install ships a version-matched koja-lsp alongside the koja compiler on your $PATH. Nothing else to do.
Building Koja from source instead? Follow the Koja installation guide.

Or point the extension at specific binaries in your settings:

{
  "koja.path": "/absolute/path/to/koja",
  "koja.lsp.path": "/absolute/path/to/koja-lsp"
}

2. Install the extension. Install Koja Language from Open VSX, the registry used by Cursor, VSCodium, Windsurf, and other VS Code-compatible editors. Search for "Koja" in your editor's extensions view, or install from the Open VSX page.

Alternatively, build from source: clone this repository, then

npm install
npm run package          # produces koja-<version>.vsix via @vscode/vsce

and run Extensions: Install from VSIX… from the command palette, selecting the generated file. (To hack on the extension itself, press F5 to launch an Extension Development Host instead.)

Features

Syntax highlighting for .koja and .kojs files, and Koja code blocks in Markdown.
Language-server features via koja-lsp: diagnostics, hover, completion, signature help, go-to-definition, find references, rename, document highlight, inlay hints, document and workspace symbols, and folding.
Format on save through koja format.
A Testing view. Every test "..." block in a project's src/ and test/ appears in the tree, and a run executes koja test for the project and shows each result inline. A failed assert shows the expression, the message, and a diff of both sides at the assertion line.
Commands to run and build the current file, and to test the current project.

Commands

Command	Description
`Koja: Run File`	Run the current `.kojs` or project.
`Koja: Build File`	Build the current `.kojs` or project.
`Koja: Test Project`	Run `koja test` for the current project.
`Koja: Restart Language Server`	Restart `koja-lsp`.

For a .koja file, the extension selects the nearest koja.toml with koja -S. The shared terminal keeps its working directory. A .kojs script still runs by its file path.

koja test has no per-test filter, so running one test from the Testing view runs its whole project and reports every result.

Settings

Setting	Description
`koja.path`	Path to the `koja` CLI binary. Empty searches `$PATH`.
`koja.lsp.path`	Path to the `koja-lsp` binary. Empty searches `$PATH`.

Contributing

Repository layout:

src/extension.ts: entry point that launches the koja-lsp client and registers the run, build, test, and restart commands.
src/tests.ts: the Testing view. Finds test blocks and maps koja test --reporter json events to results.
src/project.ts: locates koja.toml projects and their sources.
syntaxes/: TextMate grammars (koja.tmLanguage.json plus a Markdown code-block injection).
language-configuration.json: brackets, comments, auto-indent, and folding rules.

Build with npm run compile (or npm run watch for incremental builds), then press F5 to try changes in an Extension Development Host. Build outputs (out/, *.vsix) are gitignored.

Koja Language