Configuration
Configure language servers globally and for individual workspaces.
Context Engine uses language servers installed on your system. It ships configuration for recommended servers, but it does not bundle the server binaries.
Why Context Engine recommends primary servers
Language servers for the same language are not interchangeable. They can differ in type inference, especially for dynamically typed languages, workspace symbol search, navigation, documentation, and other semantic capabilities.
The bundled defaults choose a primary server for each language based on the capabilities Context Engine relies on. Some common selections are:
| Ecosystem | Preconfigured primary |
|---|---|
| Rust | rust-analyzer |
| Go | gopls |
| TypeScript and JavaScript | vtsls |
| Python | basedpyright-langserver |
You are free to use different language servers. A language entry can select a primary server and ordered fallbacks. Configure each server's command, arguments, initialization options, and workspace settings as required.
Global and workspace configuration
The global configuration is stored at:
- Linux and macOS:
~/.context-engine/config.toml - Windows:
~\.context-engine\config.toml(%USERPROFILE%\.context-engine\config.toml)
The workspace configuration is stored at .context-engine/config.toml in the repository root.
First workspace initialization
When Context Engine initializes a workspace:
- If the global configuration does not exist, Context Engine creates it from the bundled defaults.
- If the workspace configuration does not exist, Context Engine copies the global configuration into the repository.
- When Context Engine creates the workspace
.context-engine/directory, it adds.context-engine/to the root.gitignore.
The workspace configuration overrides global language entries with the same language ID. Use the global file as your reusable baseline and the workspace file to select and tune language servers for one repository.
Workspace symbol limits
Some language servers limit workspace/symbol results by default. A low cap can make grep_definition symbol search incomplete and unreliable.
When the server exposes a workspace-symbol limit, we recommend setting it high—for example, 100000. The bundled rust-analyzer configuration already applies this value.
The option name and location are specific to each language server. Set the limit through that server's initialization options or workspace configuration as appropriate.
How Context Engine selects a language
When several configured languages claim the same file extension or glob, Context Engine resolves the conflict in this order:
- Collect every matching candidate in configuration order.
- If there is only one candidate, use it.
- If there are multiple candidates, check project roots from the file upward; the nearest matching root wins.
- If project roots do not resolve the conflict, use the first candidate in the configuration.
To resolve an ambiguity, remove or comment out languages you do not use, add project-specific roots, or reorder the entries so the preferred language appears first.
Known overlaps in the bundled defaults
| Extension | Candidates | Default resolution |
|---|---|---|
.v | V, Coq, Verilog | V and Coq define project roots; otherwise configuration order applies. |
.s, .S | Assembly, GAS | Configuration order applies. |
.scm | Scheme, Tree-sitter Query | Configuration order applies. |
.inc | PHP, Pascal, SourcePawn, BitBake | PHP uses project roots and BitBake uses project globs; otherwise configuration order applies. |
.fs | F#, Forth | F# defines project roots; otherwise configuration order applies. |