hledger-vscode

VS Code extension for hledger the plain text accountingtool, powered by the hledger-lsp language server.

Features

This extension provides full IDE support for hledger journal files (.journal, .hledger):

Intelligent completion for accounts, payees, commodities, and tags
Validation with configurable rules (balance checking, date ordering, undeclared items, etc.)
Auto formatting with automatic commodity formatting and column alignment throughout the journal file
Navigation (go to definition, find references, document/workspace symbols)
Code actions (add declarations, rename refactoring)
Inlay hints for inferred amounts, running balances, and cost conversions
Semantic highlighting for richer syntax coloring
Multi-file support via include directives with automatic or configurable root file detection

For a complete feature list and examples, see the hledger-lsp server documentation.

Installation

Install from the VS Code marketplace or the Extensions view (Ctrl+Shift+X).

The extension will start automatically when you open a .journal or .hledger file.

Quick Start

Install the extension
Open a hledger journal file (.journal or .hledger)
Start editing! The language server provides completions, diagnostics, and more

Example Settings

Add to your VS Code settings.json or set in the Settings UI:

{
  "hledgerLanguageServer.inlayHints.showInferredAmounts": true,
  "hledgerLanguageServer.inlayHints.showRunningBalances": true,
  "hledgerLanguageServer.validation.undeclaredAccounts": true
}

For all available settings, see the Server Configuration Documentation.

Commands

Available via the Command Palette (Ctrl+Shift+P):

Reload Language Server (hledgerLanguageServer.reload) - Restart the server
Show Language Server Log (hledgerLanguageServer.showLog) - View server output
Toggle Inlay Hints (hledgerLanguageServer.toggleInlayHints) - Show/hide all inlay hints
Toggle Validation (hledgerLanguageServer.toggleValidation) -Enable/disable all validation

Configuration

The extension exposes all language server settings under the hledgerLanguageServer prefix. Main categories:

Validation (hledgerLanguageServer.validation.*) - Toggle individual validation rules
Formatting (hledgerLanguageServer.formatting.*) - Configure indentation and alignment
Inlay Hints (hledgerLanguageServer.inlayHints.*) - Control which hints to display
Completion (hledgerLanguageServer.completion.*) - Filter completion suggestions
Severity (hledgerLanguageServer.severity.*) - Set diagnostic severity levels

For detailed documentation of all settings, visit the server configuration guide.

Status Bar

The extension adds a status bar item showing the server state:

Click it to open the Language Server output channel
Shows: starting, running, reloading, or stopped

Development

Using Published Server (Recommended for Contributors)

Clone this repository:

git clone https://github.com/ptimoney/hledger-vscode.git
cd hledger-vscode

Install dependencies:
```
npm install
```
Build:
```
npm run compile
```
Press F5 in VS Code to launch Extension Development Host
Open a .journal file to test

Changes to the extension require npm run compile and reloading the dev host.

Using Local Server (For Server Development)

If you're also developing the language server:

Clone and link the server:

cd /path/to/hledger-lsp
npm install && npm run build
npm link

Link in extension:

cd /path/to/hledger-vscode
npm link hledger-lsp
npm run watch  # or compile

Press F5 to test changes

Server changes require npm run build in the server directory, then reload the Extension Development Host.

To revert to the published package:

npm unlink hledger-lsp
npm install

License

MIT

Contributing

Found a bug or have a feature request? Please open an issue

For server-side bugs (parsing, validation, LSP features), please report them in the hledger-lsp repository.

hledger-lsp

patrickt