LedgerBoard

Your Kanban board should survive the tool that displays it.

LedgerBoard is a local-first VS Code board whose source of truth is three readable Markdown files. It adds a polished drag-and-drop workflow, named task assignees, flexible label palettes, conflict-safe autosave, and append-only analytics without an account, database, server, or proprietary export.

Highlights

• Exact, line-numbered diagnostics for card separators, malformed description continuations, mixed line endings, missing labels, malformed checkboxes, and first source/serialized differences.
• Guided Repair Board Bundle workflow that previews safe changes, validates the result, and keeps a restore point.
• Faster initialization and multi-root discovery with parallel direct file reads, bounded probes, active-board reuse, and visible progress.

Why LedgerBoard

• Markdown stays authoritative. Review every change in Git and edit the files with any text editor.
• Local-first by design. No telemetry, cloud sync, login, or hosted service.
• Useful beyond software teams. Labels can represent projects, clients, products, teams, or workstreams.
• History without a database. Semantic create, move, update, and delete events append to a readable ledger.
• Safe around human edits. Saves stop when a Markdown buffer changed outside the board.
• Fast at runtime. The extension has no runtime package dependencies.

Quick Start

1. Open a folder in VS Code.
2. Run LedgerBoard: Initialize Board in Folder from the Command Palette.
3. Add people and labels, assign tickets, and drag cards between columns.
4. Commit the resulting Markdown diff when you are ready.

Initialization creates only missing files and never overwrites an existing one:

BOARD.md
KANBAN-CONFIG.md
KANBAN-HISTORY.md

Run LedgerBoard: Open Board whenever you want to return. In a multi-root workspace, LedgerBoard checks workspace roots first, validates candidates in parallel, and lets you choose when needed.

Standalone browser app

media/index.html is also a complete offline application. Copy that one file into an air-gapped environment, open it in a current Chrome or Edge browser, and choose the folder containing BOARD.md, KANBAN-CONFIG.md, and KANBAN-HISTORY.md. The app reads and writes those files directly, includes all styles and scripts inside the HTML file, and makes no network requests.

Browser folder access requires the File System Access API. The VS Code extension remains the compatible option for browsers that do not provide it.

Features

Board

• Inbox, Next, Doing, Review / Blocked, and Done workflow
• Unlimited tickets in every column
• P1-P4 priorities
• Search and label, assignee, and priority filters
• Responsive desktop and narrow-editor layouts
• Clear destination and insertion indicators while dragging tickets
• One-second autosave with visible pending, saving, saved, and blocked states
• Left-click card editing and a right-click action menu for contextual edit and confirmed delete actions
• Append-only deletion history that remains visible in analytics activity without affecting current board totals

People, labels, and appearance

Add people by name in the People & labels view, then optionally assign a ticket in its editor. Assigned people appear on cards with compact avatars and can be used to filter the board. Assigning, reassigning, and clearing an assignee writes the previous and new person IDs to the history ledger.

Every card has an area linked to a label. A label can represent a project, account, product, team, department, or any grouping that makes the board useful. Names and colors live in KANBAN-CONFIG.md, alongside the people directory, board title, timezone, accent, and density. Reassign current cards before removing their label so every card keeps a valid area.

Analytics

• A dedicated, local-only analytics workspace with date, search, status, priority, label, and assignee filters.
• Board health metrics for open, blocked, aging, completed, reopened, and net-changing work, with comparison to the preceding equivalent period.
• Separate work-in-progress status, priority, and label views from completed-work throughput, so historical completed volume does not obscure current work. Both have keyboard-accessible drill-downs to their supporting tickets.
• Daily, weekly, or monthly completed-work throughput from recorded arrivals in the configured completion column, with preceding-period comparison, lead and cycle-time ranges, and time-in-status summaries that state their data coverage.
• Aging, unassigned-work, duplicate-looking-title, missing-description, stale-activity, and inconsistent-history checks.
• Cautious throughput forecasting after sufficient history, expressed as a range rather than a promised delivery date.
• Locally saved filter settings and a local JSON export of filtered, non-sensitive aggregate data and metric definitions.

Existing boards begin with honest baseline observations. LedgerBoard never invents old creation or completion dates. Baseline observations are displayed as lower bounds and are excluded from lead-time, cycle-time, and time-in-status calculations.

Commands

You can also right-click a folder in Explorer and choose Initialize Board in Folder.

The command is displayed as LedgerBoard: Add Ticket while its existing ledgerBoard.addOutcome identifier remains stable for automation.

Markdown Contract

A card is deliberately small:

- [ ] AO-001 — Prepare the architecture review · P2 · area:project-alpha
    - **Description:** Consolidate the decisions, risks, and recommended next steps.
    - **Assignee:** alex-smith

Status is the section containing the card. Description and Assignee are optional details. The full, versioned contract is in BOARD-STANDARDS.md, including a ready-to-paste prompt for coding agents that generate compatible boards.

Adjacent cards require exactly one blank physical line:

- [ ] AO-001 — First ticket · P1 · area:project-alpha
    - **Description:** First description.

- [ ] AO-002 — Second ticket · P2 · area:project-alpha
    - **Description:** Second description.

Descriptions can span multiple lines. LedgerBoard stores each continuation with six spaces in Markdown and preserves the same line breaks in the card editor. It reports exact card IDs and line numbers for separator, description-continuation, mixed-line-ending, and first-difference errors.

    - **Description:** First line of context.
      Additional context on the next line.

Troubleshooting

Board does not open

Run LedgerBoard: Validate Board Bundle. The error identifies the first actionable issue. If the issue is formatting-only or a ticket references a missing label or person, choose Review repair. LedgerBoard shows every proposed change before writing, saves the original three-file bundle in .ledgerboard-repair-backup.json, and validates the repaired result. Restore that snapshot with LedgerBoard: Restore Latest Board Repair Backup if the repaired board is unexpected.

Ambiguous data such as duplicate identifiers, duplicate directory entries, malformed configuration, or malformed history is never changed automatically. The repair view identifies the affected file and explains the manual correction that is still required.

Formatting normalization

Normalize BOARD.md Formatting previews the issues and asks for confirmation. It fixes only safe, non-semantic formatting: missing/extra blank separator lines and mixed line endings. It does not add history events or modify card content.

Large or multi-root workspaces

LedgerBoard checks root bundles before recursive discovery, probes roots in parallel, reads candidate files directly, and bounds slow filesystem probes. Common commands reuse the active board rather than rescanning the workspace.

Intentional limitations

LedgerBoard deliberately does not provide subtasks, due dates, estimates, cloud synchronization, or a mobile client. Those constraints keep the Markdown contract small, deterministic, reviewable in Git, and durable without the extension.

Privacy and Trust

LedgerBoard does not collect telemetry and does not make network requests. It reads and writes only the three Markdown files in the board folder selected through the workspace. Webview scripts use a strict Content Security Policy, and every save is validated again in the extension host.

The extension supports untrusted and virtual workspaces because it never executes workspace content. As always, review source-control changes before sharing a board that may contain private information.

Requirements

• VS Code 1.103 or later
• A writable workspace for editing (read-only virtual workspaces can still be inspected)

There are no external runtime dependencies.

See CONTRIBUTING.md, SECURITY.md, and SUPPORT.md before opening a pull request or security report.

License

MIT