Better Welcome
A better welcome for VS Code — browse your projects like a music library. Better Welcome opens to a cover-art view of your disk: every folder is a card, and folders that are projects — Git repositories, Node, Rust, Python, Go, CMake, PlatformIO, Java, .NET, Docker and more — light up with their technologies, branch, dirty state and description. Click a project to read its README, browse its files and inspect its Git state without opening it as your workspace.
Getting started
- Run Better Welcome: Open Library (
Ctrl+Alt+W / ⌘⌥W).
- You land on Browse — your home folder, drives and common code folders are one click away. Walk into any folder; project cards appear as they are detected.
- Single click a project card to inspect it. Open Project (or
Ctrl/⌘+Enter) is the only thing that changes your workspace.
- Like a folder full of projects? Add to Library indexes it (recursively, nested projects included) so it is searchable, sortable and always up to date in the Library tab.
What you get
- Browse — a filesystem browser with album-cover cards, places shelf (Home, Desktop, Documents, code folders, drives/volumes, workspace folders, library roots), breadcrumb path bar, hidden-file toggle, sorting, file preview drawer.
- Library — indexed projects in grid, compact, list or hierarchy layouts; instant search; quick filters (Recent, Active, Dirty, Archived); pinning, archiving, hiding.
- Project detail — Overview (health, technologies, recent commits, README excerpt, notes, subprojects, location), README with images and relative links, lightweight file browser with safe text/Markdown/image preview, Git (branch, tracking, ahead/behind from local refs, working tree, commits), private Notes, Metadata overrides.
- Nested projects and monorepos — hierarchy is preserved; subprojects reference their owning repository instead of duplicating Git work.
- Project config — optional
.betterwelcome.json (or .projectlibrary.json) with name, description, tags, group, readme, icon, cover. Cover images are also picked up from cover|banner|logo|icon.(png|jpg|webp|gif|svg) in the root, docs/, assets/ or .github/.
What it never does
- Never runs project code — manifests are read, not executed.
- Never writes into your repositories — notes, tags, pins and overrides live in the extension's storage.
- Never touches the network — no fetch, no telemetry, no uploads. Ahead/behind counts come from local refs only.
- Never scans your disk at startup — the library renders from cache first; refresh is visible-first and bounded.
Commands
| Command |
What it does |
Better Welcome: Open Library |
Opens the Better Welcome tab (Browse or Library, see betterWelcome.startPage) |
Better Welcome: Browse Folder… |
Picks a folder and opens it in Browse |
Better Welcome: Search Projects |
Quick Pick over indexed projects; opens the picked project's detail |
Better Welcome: Add Library Root |
Adds a folder to the library and scans it |
Better Welcome: Rescan All |
Rescans all library roots |
Settings
| Setting |
Default |
Description |
betterWelcome.libraryRoots |
[] |
Folders indexed by the Library |
betterWelcome.startPage |
browse |
browse or library |
betterWelcome.browse.showHidden |
false |
Show dot files/folders while browsing |
betterWelcome.defaultView |
grid |
grid, compact, list, hierarchy |
betterWelcome.commitCount |
3 |
Recent commits shown (3/5/10/20) |
betterWelcome.scanner.maxDepth |
8 |
Discovery depth below each root |
betterWelcome.scanner.followSymlinks |
false |
Follow directory symlinks during discovery |
betterWelcome.scanner.ignore |
[] |
Extra ignore patterns (defaults cover node_modules, target, dist, .venv, …) |
betterWelcome.git.enabled |
true |
Read Git state (read-only CLI) |
betterWelcome.git.timeoutMs |
3000 |
Per-command Git timeout |
betterWelcome.preview.maxFileSize |
1048576 |
Text preview size limit |
Requirements
- VS Code 1.85+.
- Git on
PATH for Git information (everything else works without it).
| |
