LSP

Aura integrates with Language Server Protocol (LSP) servers to provide real-time compiler diagnostics after tool execution. Errors and warnings from running language servers are appended to tool results so the LLM can observe and fix them without an explicit step.

Config Location

.aura/config/lsp/*.yaml

Each file is a YAML map of server names to definitions. Multiple servers can live in one file, or each in its own file.

Server Fields

Field	Type	Default	Description
command	string		Binary name or path to the language server executable
args	[]string	[]	Command-line arguments passed to the server
file_types	[]string	[]	File extensions this server handles (e.g. [go, mod]). Empty = all types
root_markers	[]string	[]	Files that must exist in the working directory to start the server
settings	object	{}	Workspace settings sent via workspace/didChangeConfiguration
init_options	object	{}	LSP initialization options sent during the initialize handshake
timeout	int	30	Seconds to wait for the server to initialize before giving up
disabled	bool	false	Skip this server without removing its config

root_markers

When root_markers is set, the server only starts if at least one listed file exists in the working directory. Use this to avoid starting language servers in unrelated projects:

gopls:
  root_markers: [go.mod]   # only starts in Go projects

Tools

LSP provides two opt-in tools:

Diagnostics

Returns compiler diagnostics (errors and warnings) from all active LSP servers. Servers are lazily started on first use.

Parameter	Required	Description
path	No	File path to get diagnostics for. Omit for all open files

LspRestart

Restarts LSP servers. Use when servers are misbehaving or after changing project configuration.

Parameter	Required	Description
server	No	Server name to restart. Omit to restart all servers

Both tools are opt-in — they are hidden unless explicitly enabled by name in an agent, mode, task, or features/tools.yaml:

# Enable for a specific agent
---
tools:
  enabled: [Diagnostics, LspRestart]
---

# features/tools.yaml — enable globally
tools:
  enabled:
    - Diagnostics
    - LspRestart

See Opt-In Tools for the full opt-in mechanism.

Diagnostic Pipeline

Diagnostics run after hooks complete. This ensures formatters and fixers (e.g. gofmt, golangci-lint --fix) have already modified files before the LSP server is asked to evaluate them:

1. Tool executes (e.g. Patch, Write)
2. Post hooks run (formatters, fixers)
3. LSP diagnostics collected for modified files
4. All feedback appended to the tool result returned to the LLM

Example Configuration

# .aura/config/lsp/gopls.yaml
gopls:
  command: gopls
  args: [serve]
  file_types: [go, mod]
  root_markers: [go.mod]
  settings:
    directoryFilters: ["-**/vendor", "-**/node_modules", "-.git"]
    staticcheck: true
  timeout: 30

# .aura/config/lsp/typescript.yaml
typescript:
  command: typescript-language-server
  args: [--stdio]
  file_types: [ts, tsx, js, jsx]
  root_markers: [package.json, tsconfig.json]
  timeout: 30

# .aura/config/lsp/pyright.yaml
pyright:
  command: pyright-langserver
  args: [--stdio]
  file_types: [py]
  root_markers: [pyproject.toml, setup.py, setup.cfg]
  timeout: 30

Server Lifecycle

• Servers start lazily when a matching file is first encountered.
• Servers run for the duration of the session and are stopped on exit.
• disabled: true skips a server at startup without removing its config.
• LspRestart can recover a misbehaving server without restarting Aura.