Transform your plain text accounting experience with powerful IDE capabilities:

• Context-aware suggestions based on cursor position
• Frequency-based prioritization for accounts and payees
• Transaction templates - type a payee name to insert complete transactions with accounts and amounts based on history
• Inline ghost text - see suggestions as you type, press Enter to accept
• Complete support for dates, accounts, payees, commodities, tags, and directives
• Works as you type - no keyboard shortcuts needed

• LSP-powered highlighting: Semantic tokens from the Language Server for precise syntax coloring
• Theme integration: Adapts to your VS Code theme automatically
• Customizable colors for all hledger elements

• Smart alignment for amounts and comments
• Format on save - keep your journals tidy automatically
• Multi-currency support with international number formats
• Commodity-aware formatting - amounts formatted according to commodity directives
• Preserves balance assertions, virtual postings, and metadata

• Real-time balance checking - validates transactions on save
• Multi-commodity support - each currency balanced separately
• Inferred amounts - supports single posting without amount
• Cost notation - supports @ (unit cost) and @@ (total cost)
• Balance assertions - handles =, ==, =* syntax

• On-type formatting via LSP - auto-indent and amount alignment as you type
• Multi-language Unicode support (Cyrillic, Asian languages, etc.)

• Insert balance sheets, income statements, and statistics directly into journals
• Automatic journal file detection
• Results formatted as comments

• Project-based caching for large journal files
• Incremental updates - only reparse changed files
• Efficient workspace parsing

• Required LSP backend, auto-installed on first activation
• Auto-download of LSP binary from GitHub releases
• Status bar indicator showing LSP state (Running, Error, etc.)
• Output channel for diagnostics (View → Output → HLedger)
• Guided walkthrough for new users (Command Palette → "Get Started: HLedger")
• CodeLens balance check indicators on transactions (opt-in)
• Cross-platform support (macOS, Linux, Windows)

Option 1: VS Code Marketplace (Recommended)

1. Open VS Code
2. Press Ctrl+Shift+X (Extensions)
3. Search for "hledger"
4. Click Install

Option 2: Quick Install

• VS Code Marketplace
• Open VSX Registry

Supported files: .journal, .hledger, .ledger

1. Create or open a .journal, .hledger, or .ledger file
2. Accept LSP installation when prompted on first activation
3. Start typing - auto-completion activates automatically
4. Press Enter after transaction dates - LSP handles indentation
5. Save file - automatic formatting aligns everything

2025-01-15 * Coffee shop
    Expenses:Food:Coffee        $4.50
    Assets:Cash                -$4.50

Type and get instant suggestions:

• Start line with 2025 → Date completions
• After date, type Cof → Payee completions
• Indent and type Exp → Account completions
• Type $ after account → Commodity completions
• Add ; and type # → Tag completions

Insert hledger reports directly into your journals as formatted comments.

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

• HLedger: Insert Balance Report - Balance sheet with assets/liabilities
• HLedger: Insert Income Statement - Revenue and expense summary
• HLedger: Insert Statistics Report - File stats and metrics

Example output:

; hledger bs - 2025-11-08
; ==================================================
; Balance Sheet 2025-01-04
;              ||  2025-01-04
; =============++=============
;  Assets      ||
; -------------++-------------
;  Assets:Bank || 2450.00 USD
; -------------++-------------
;              || 2450.00 USD
; =============++=============
;  Liabilities ||
; -------------++-------------
; -------------++-------------
;              ||           0
; =============++=============
;  Net:        || 2450.00 USD
; ==================================================

Journal file resolution (priority order):

1. LEDGER_FILE environment variable (validated for security)
2. hledger.cli.journalFile setting (validated for security)
3. Current open file (trusted from VS Code)

Security Note: Paths from environment variables and configuration settings are validated to prevent command injection attacks. Shell metacharacters and inaccessible paths are rejected.

Import bank statements and transaction data from CSV/TSV files.

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

• HLedger: Import Selected Tabular Data - Import selected text as CSV/TSV
• HLedger: Import Tabular Data from File - Import active file as CSV/TSV

Features:

• Auto-detection of delimiters (comma, tab, semicolon, pipe)
• Smart column detection with multi-language headers (English/Russian)
• Account resolution via journal history, category mapping, and merchant patterns
• Date format detection supports multiple formats (YYYY-MM-DD, DD.MM.YYYY, etc.)

Account Resolution Priority:

1. Journal history - Uses your existing transactions to match payees to accounts
2. Category mapping - Maps CSV category column to hledger accounts
3. Merchant patterns - Regex patterns for common merchants
4. Amount sign - Fallback heuristic (positive=income, negative=expense)

Configuration:

{
  "hledger.import.useJournalHistory": true,  // Learn from existing transactions
  "hledger.import.defaultDebitAccount": "expenses:unknown",
  "hledger.import.defaultCreditAccount": "income:unknown"
}

{
  // Auto-completion
  "hledger.autoCompletion.enabled": true,
  "hledger.autoCompletion.maxResults": 25,
  "hledger.autoCompletion.transactionTemplates.enabled": true,  // Suggest full transactions based on history

  // Inline completions (ghost text)
  "hledger.inlineCompletion.enabled": true,
  "hledger.inlineCompletion.minPayeeChars": 2,  // Min chars before showing suggestions

  // Formatting
  "editor.formatOnType": true,   // Enable on-type formatting (Enter/Tab via LSP)
  "editor.formatOnSave": true,   // Enable auto-formatting on save

  // CLI integration
  "hledger.cli.path": "",  // Auto-detected if empty
  "hledger.cli.journalFile": "",  // Uses LEDGER_FILE if empty

  // Optional: Disable semantic highlighting to use only TextMate grammar
  "hledger.features.semanticTokens": true,  // Enabled by default

  // Validation diagnostics
  "hledger.diagnostics.enabled": true,  // Disable to turn off validation warnings

  // Formatting
  "hledger.formatting.amountAlignmentColumn": 40  // Column for amount alignment (20-120)
}

Customize syntax colors for any theme:

{
  "editor.semanticTokenColorCustomizations": {
    "rules": {
      "account:hledger": "#0EA5E9",
      "amount:hledger": "#F59E0B",
      "payee:hledger": "#EF4444",
      "tag:hledger": "#EC4899",
      "commodity:hledger": "#A855F7"
    }
  }
}

Available tokens: account, accountVirtual, amount, date, time, commodity, payee, note, tag, tagValue, directive, code, status, link

• Large files? Project-based caching handles them efficiently
• Format not working? Ensure editor.formatOnSave is enabled
• Custom hledger path? Set hledger.cli.path in settings
• Want more precision? Enable semantic highlighting for enhanced token identification
• Multiple currencies? The formatter handles them automatically

Having issues? Check our comprehensive Troubleshooting Guide:

• 🚫 Completions not working
• 🐌 Performance with large files
• ⏱️ CLI timeouts
• 🎨 Syntax highlighting issues

Quick fixes:

• Reload window: Ctrl+Shift+P → "Reload Window"
• Manual completion: Ctrl+Space
• Verify file extension: .journal, .hledger, or .ledger

→ Full Troubleshooting Guide

New to hledger?

• Official Tutorial
• Example Files
• Accounting Concepts
• CLI Reference

For complete documentation including all configuration options, keyboard shortcuts, and advanced features, see the User Guide.

Contributions are welcome! Feel free to:

• Report bugs and request features via GitHub Issues
• Submit pull requests
• Improve documentation

MIT License - see LICENSE file for details.

• hledger Official Site
• Plain Text Accounting
• VS Code Marketplace
• GitHub Repository