Handbook

Workspace setup — When projects or scans look wrong

The usual fix when Projects looks empty, scans seem wrong, or repos do not match what you expect: set LENSES_WORKSPACE_ROOT to the parent folder your team agreed on, restart the Lenses server, and reload the browser to…

How-To · Updated

What it is

The usual fix when Projects looks empty, scans seem wrong, or repos do not match what you expect: set LENSES_WORKSPACE_ROOT to the parent folder your team agreed on, restart the Lenses server, and reload the browser to confirm Projects. Use this page after you have already picked a layout and root in Choosing the root but the UI still misbehaves.

Parent: Workspace setup.

When to use it

  • You have chosen a layout and root, but scans stay empty, permissions fail, or caches land in the wrong place.

Prerequisites

  • Install and run completed.
  • Shell access to the machine that runs the server.

Steps (what most people need)

  1. Set the workspace root — Set LENSES_WORKSPACE_ROOT to the parent folder that contains your clones (the directory that lists forge-lenses/ next to other repos in a sibling layout, or the host root in a nested layout). Restart the server after every change.

  2. Verify — Reload the app and confirm Projects lists the repos you expect under that parent.

  3. Still wrong? — Re-read Choosing the root and make sure the path matches your intended workspace (not a single clone unless that is deliberate). Then repeat step 1.

Advanced note — submodule / host layout (optional)

Most teams can skip this. It matters when forge-lenses lives inside another repo (for example as a submodule) and you want local caches and shared notes at the host repository root instead of under forge-lenses/.

  • Optional registry — Some teams add workspace-registry.json at the forge-lenses repo root to label repos or tune scanning. Prefer starting without it unless your team’s internal doc or maintainer already requires it.

  • Host startup script — When using that nested layout, your team may run ./scripts/lenses-startup.sh once from the host root so .lenses-local/ and .lenses-repo/<login>/ are created next to your product tree (not inside forge-lenses/). Follow whatever your team documents for that layout.

For desktop-app, JSON APIs, or contributor-level detail, use the forge-lenses repository on GitHub — not this handbook.

Worked example — env var forgotten

Symptom: Server starts, but Projects is empty or shows only the Lenses repo.

Likely mistake: LENSES_WORKSPACE_ROOT unset or still pointing at an old path.

Fix: Follow Steps above: set the variable to your agreed parent (see Choosing the root), restart, reload the browser.

Worked example — caches under the wrong directory

Symptom: Teammates see different local data paths; backups omit .lenses-local/.

Likely mistake: Using a nested / submodule layout without the host-root setup your team expects; caches were created under forge-lenses/ instead of the host.

Fix: If your team nests Lenses in a product repo, see Advanced note — submodule / host layout above (startup script and cache locations). Otherwise, confirm LENSES_WORKSPACE_ROOT and the host layout with whoever maintains your workspace doc.

Symptom → likely mistake → fix

Symptom Likely mistake Fix
Permission denied in logs Server user cannot read some repos under the root Fix filesystem permissions or move clones to a readable path
Scan never finishes Root too broad (e.g. home directory) Narrow LENSES_WORKSPACE_ROOT
Still wrong after env var + restart Optional registry or maintainer-only overrides Ask your maintainer or see forge-lenses on GitHub — avoid editing workspace-registry.json unless your team owns that workflow
Need desktop-app or JSON details — Maintainer docs for forge-lenses on GitHub

Scan order (visual)

Set LENSES_WORKSPACE_ROOT
    |
    v
restart
    |
    v
confirm Projects; if nested host layout, see advanced note for startup and caches

Expected outcome (plain language)

  • The server process and your team’s agreed workspace path line up after a restart.
  • If you use a host layout, local state directories end up where your team expects (see advanced note when relevant).
  • Troubleshooting for “wrong repos” is about paths and data, not unexplained empty UI.

How to verify success

  • After restart, Projects reflects the root you set; permission errors in the terminal are gone or explained.

What to do next