# Lightwell

> Lightwell is a live architecture map for a codebase. The `lightwell` CLI extracts a JSON facts map from Rust workspaces, TypeScript/JavaScript (including React and Next.js), HTML/CSS, Python, Go, and C# and VB.NET projects: crates, app entry points, modules, imports, top-level classes and functions, Cargo features, dependency edges and source fingerprints. A desktop app and a browser viewer draw the map. Project notes live in `.lightwell/notes.json`. Lightwell has no MCP server; agents use the CLI, which writes JSON.

This file is for agents. Full docs: https://getlightwell.app/llms-full.txt. Command list: https://getlightwell.app/agents.json. Source: https://github.com/moonbase2090/lightwell (MIT).

## Languages

Extraction is on by default for:

- Rust workspaces: crates, modules, and Cargo features.
- TypeScript, JavaScript, HTML, and CSS, including React and Next.js.
- Python modules, imports, and top-level classes and functions.
- Go packages, files, imports, and top-level functions, methods, and types.
- C# and VB.NET solutions and projects, namespaces, types, and methods.

## Prerequisites

- macOS 11.0 or later (Apple silicon or Intel), Linux x86_64 (glibc 2.28 or later) or ARM64, or Windows x64.
- Optional: Cargo on PATH. With it, extraction uses `cargo metadata --no-deps`; without it, Lightwell reads manifests and sources directly.
- From source: a stable Rust toolchain (CLI), Node.js 22 (viewer), and the Tauri v2 prerequisites (desktop app).

## Install

Release v0.1.15 and checksums (`SHA256SUMS`): https://github.com/moonbase2090/lightwell/releases/latest

### macOS

Download `Lightwell_0.1.15_aarch64.dmg` (Apple silicon) or `Lightwell_0.1.15_universal.dmg` (Intel and Apple silicon) from the release, open it, and drag Lightwell to Applications. The images are signed and notarized.

### Linux

```sh
# Debian/Ubuntu (x86_64)
sudo apt install ./Lightwell_0.1.15_amd64.deb
```

Other x86_64 options: `Lightwell_0.1.15_amd64.AppImage`, `Lightwell_0.1.15_x86_64.rpm`, or the portable `Lightwell_0.1.15_linux_x86_64.tar.gz` (unpacks to `lightwell/` with an `install.sh`). ARM64: `Lightwell_0.1.15_linux_aarch64.tar.gz` carries the CLI.

### Windows

Run `Lightwell_0.1.15_x64.msi`. `Lightwell.exe` is the desktop app and `bin\lightwell.exe` is the CLI; the installer adds that `bin` directory to the user PATH (pass `ADDTOPATH=0` to msiexec to skip).

### Build from source

```sh
git clone https://github.com/moonbase2090/lightwell.git && cd lightwell
cargo install --path crates/lightwell-cli          # CLI
npm ci && npm run dev                               # browser preview
npm ci && npm run tauri:dev                         # desktop app (Tauri v2)
```

Windows package: `powershell -File scripts/release/build-windows.ps1` (Node.js 22, Rust, WiX 5.0.2).

## Configuration

- `LIGHTWELL_EDITOR_TEMPLATE` — command used by `lightwell open`, with `{file}`, `{line}`, `{column}` placeholders, e.g. `code --goto {file}:{line}:{column}`. Not run through a shell. Falls back to `VISUAL`, then `EDITOR`. Default handler: `open` (macOS), `xdg-open` (Linux), `cmd /C start` (Windows).
- Project notes file: `.lightwell/notes.json` in the workspace root, created on first save.
- Build flag: `VITE_ENABLE_PROJECT_NOTES=false` omits the notes UI from a desktop build.
- The desktop app's update check is on by default and can be turned off in Settings.

## Tools

CLI commands (`lightwell`):

- `lightwell extract <repository> -o <facts.json> [--name <label>]` — extract a facts map to a JSON file. Paths in the output are relative to the repository. Example: `lightwell extract . --name MyProject -o /tmp/map.json`
- `lightwell watch <repository> [--name <label>]` — stream a complete map as JSON Lines to stdout, and a new one whenever source fingerprints change. Ctrl-C stops it. Example: `lightwell watch . --name MyProject`
- `lightwell notes list` — list project notes; marks a note stale when its block is missing or its fingerprint changed. Run from the workspace root.
- `lightwell notes set <block-id> <text...>` — save a note for a block (use a `blocks[].id` from the map). Example: `lightwell notes set crate:my-core "Review output serialization"`
- `lightwell notes rm <block-id>` — remove a note.
- `lightwell open <block-id>` — extract the current map and open the block's source file at line 1, column 1 in the configured editor. Example: `lightwell open crate:my-core`
- `lightwell --version`, `lightwell help`.

## Usage workflows

1. Understand a repo: `lightwell extract . -o /tmp/map.json`, then read `blocks[]` (ids, kinds, children) and the dependency edges from the JSON.
2. Track changes live: `lightwell watch .` and parse each JSON line as a full map.
3. Leave notes for people: `lightwell notes set <block-id> "<text>"`; review with `lightwell notes list`, clear with `lightwell notes rm <block-id>`.
4. Jump to code: `LIGHTWELL_EDITOR_TEMPLATE='<editor> {file}' lightwell open <block-id>`.
5. View the map: open the workspace folder (one with a `Cargo.toml`) in the desktop app.

## Troubleshooting

- `notes list` shows stale notes: the block is gone or its source changed. Update or remove the note; stale notes are kept until removed.
- `open` launches the wrong program: set `LIGHTWELL_EDITOR_TEMPLATE`; if it fails, `VISUAL` then `EDITOR` are tried.
- `open` lands on line 1: schema v1 does not record source spans.
- Test-only Rust modules are not in the map: they are omitted by design.
- Debian, RPM and tarball installs cannot self-update; download the latest release.

## Links

- [Full agent docs](https://getlightwell.app/llms-full.txt)
- [agents.json](https://getlightwell.app/agents.json)
- [Source](https://github.com/moonbase2090/lightwell)
- [Releases](https://github.com/moonbase2090/lightwell/releases)
- [Schema reference](https://github.com/moonbase2090/lightwell/blob/main/docs/schema.md)
- [Privacy](https://github.com/moonbase2090/lightwell/blob/main/PRIVACY.md)