VS Code Extension¶

The official VS Code extension for linthis provides seamless integration with the linthis CLI tool, offering real-time linting, formatting, and diagnostics directly in your editor.

Installation¶

From VS Code Marketplace¶

Open VS Code
Go to Extensions (Cmd/Ctrl + Shift + X)
Search for "Linthis"
Click "Install"

From Source¶

cd vscode-linthis
npm install
npm run build
# Press F5 to launch extension development host

Features¶

🔍 Real-time Linting via LSP¶

Language Server Protocol (LSP) integration
Real-time diagnostics as you type
Automatic linting on file save (configurable)
Support for multiple languages (Python, TypeScript, Rust, Go, Java, C/C++, Swift, Kotlin, and more)

🎨 Format on Save¶

Automatically format files on save
Configurable per-workspace or globally
Silent operation with output logging
Interactive prompt when enabling

🛠️ Commands¶

Linthis: Lint Document - Manually trigger linting for current file
Linthis: Format Document - Manually format current file
Linthis: Restart Language Server - Restart LSP server if needed

Configuration¶

Settings¶

All settings are prefixed with linthis.:

Basic Settings¶

{
  "linthis.enable": true,
  "linthis.executablePath": "linthis"
}

linthis.enable (boolean, default: true) - Enable/disable the extension
linthis.executablePath (string, default: "linthis") - Path to linthis executable

Automatic Features¶

{
  "linthis.lintOnSave": true,
  "linthis.formatOnSave": false
}

linthis.lintOnSave (boolean, default: true) - Lint document on save
linthis.formatOnSave (boolean, default: false) - Format document on save

Advanced Settings¶

{
  "linthis.extraArgs": [],
  "linthis.trace.server": "off"
}

linthis.extraArgs (array, default: []) - Extra arguments for LSP server
linthis.trace.server (string, default: "off") - LSP server trace level

Example Configuration¶

Minimal Setup¶

{
  "linthis.enable": true
}

Full Auto Mode¶

{
  "linthis.enable": true,
  "linthis.lintOnSave": true,
  "linthis.formatOnSave": true
}

Custom Executable Path¶

{
  "linthis.executablePath": "/usr/local/bin/linthis"
}

How It Works¶

LSP Integration¶

The extension communicates with the linthis CLI via Language Server Protocol:

Startup: Extension launches linthis lsp as a child process
Document Events: VS Code sends document changes to LSP server
Diagnostics: LSP server runs linters and sends diagnostics back
Display: Diagnostics appear in Problems panel with [linthis-ruff] prefix

Format on Save¶

When formatOnSave is enabled:

User saves file (Cmd/Ctrl + S)
VS Code saves the file to disk
Extension triggers linthis -f -i <file>
File is formatted in-place
VS Code detects change and reloads file

Lint on Save vs Format on Save¶

Feature	Lint on Save	Format on Save
Trigger	Save event	After save
Method	LSP diagnostics	CLI format
Result	Problems panel	File modification
Default	Enabled	Disabled

Usage¶

Daily Workflow¶

Open a file - LSP server starts automatically
Edit code - See real-time diagnostics in Problems panel
Save file (Cmd/Ctrl + S) - Auto-lint and format (if enabled)
Check Problems (Cmd/Ctrl + Shift + M) - Review all issues

Manual Commands¶

Press Cmd/Ctrl + Shift + P to open command palette:

Type "Linthis: Lint Document" - Manually lint current file
Type "Linthis: Format Document" - Manually format current file
Type "Linthis: Restart Language Server" - Restart if issues occur

Format on Save Setup¶

When you enable formatOnSave, you'll see a prompt:

Linthis: Format on save enabled. Format all open files now?
[Format All]  [Skip]

Format All - Immediately format all open code files
Skip - Wait until next save to format

Diagnostic Sources¶

Diagnostics in the Problems panel are prefixed with their source:

[linthis-ruff] - Python linting (ruff)
[linthis-eslint] - JavaScript/TypeScript linting (eslint)
[linthis-clippy] - Rust linting (clippy)
[linthis] - Generic linthis diagnostics

This makes it clear which tool found each issue.

Supported Languages¶

The extension supports the same languages as the linthis CLI:

Python
TypeScript / JavaScript (including React)
Rust
Go
Java
C / C++ / Objective-C
Swift
Kotlin
Lua
Dart
Shell Script
Ruby
PHP
Scala
C#

Troubleshooting¶

Extension Not Working¶

Check Output Panel: 1. View → Output 2. Select "Linthis" from dropdown 3. Look for error messages

Common Issues:

Extension is disabled - Check linthis.enable setting
Language server not running - Check if linthis is in PATH
Command not found - Install linthis CLI: cargo install --path .

No Diagnostics on Save¶

Check: 1. linthis.lintOnSave is true 2. File type is supported 3. LSP server is running (check Output panel) 4. Look in Problems panel, not Output panel

Format on Save Not Working¶

Check: 1. linthis.formatOnSave is true 2. File type is supported 3. File has no syntax errors 4. Check Output panel for error logs

LSP Server Timeout¶

If you see "Language server start timeout":

Check if linthis lsp runs successfully:
```
linthis lsp
```
Restart extension: "Linthis: Restart Language Server"
Check linthis.trace.server for detailed logs

Output Logging¶

The extension logs to the Output panel ("Linthis" channel):

Startup Logs¶

[info] Using linthis executable: linthis
[info] LSP arguments: lsp
[info] Starting language server...
[info] Language server started successfully
[info] Lint on save is enabled
[info] Format on save is enabled

Format Logs¶

[info] Format on save: /path/to/file.py
[info] Format completed

Error Logs¶

[error] Format on save failed with exit code: 1
[error] stdout: formatting errors found

Performance¶

Small Files¶

Lint: < 100ms
Format: < 200ms
Nearly instant feedback

Large Files¶

Lint: < 1s
Format: 1-3s
Consider disabling auto-format for very large files

Optimization Tips¶

Use .linthisignore to exclude large files
Disable formatOnSave for large projects
Use manual commands when needed
Configure LSP timeout if needed

Best Practices¶

Recommended Settings¶

For most projects:

{
  "linthis.enable": true,
  "linthis.lintOnSave": true,
  "linthis.formatOnSave": true
}

Per-Language Settings¶

Disable other formatters to avoid conflicts:

{
  "[python]": {
    "editor.formatOnSave": false,
    "editor.defaultFormatter": "linthis.linthis"
  },
  "[typescript]": {
    "editor.formatOnSave": false,
    "editor.defaultFormatter": "linthis.linthis"
  }
}

Workspace Settings¶

Create .vscode/settings.json in your project:

{
  "linthis.enable": true,
  "linthis.lintOnSave": true,
  "linthis.formatOnSave": true,
  "files.associations": {
    ".linthis.toml": "toml"
  }
}

Development¶

Building from Source¶

git clone https://github.com/lint-group/linthis
cd linthis/vscode-linthis
npm install
npm run build

Testing¶

Press F5 in VS Code to launch Extension Development Host.

Debugging¶

Set breakpoints in TypeScript files
Press F5 to start debugging
Use Debug Console to inspect variables

Feedback¶

Report issues at: https://github.com/lint-group/linthis/issues