task: UX, install, watcher, docs & small features (15 issues) #396

Scope

Umbrella tracker for UX, install ergonomics, watcher behavior, docs, error messaging, and small feature requests. Lower individual severity, high collective impact on first-impressions and day-to-day use.

Sub-issues

Search/regex UX

• search_code rejects paths containing & (ampersand) #272 — search_code rejects paths containing & (ampersand)
• search_code: default regex=false treats | as literal pipe, not alternation (silent 0-match trap) #282 — search_code: default regex=false treats | as literal pipe, not alternation (silent 0-match trap)
• search_code: invalid regex under regex: true silently returns empty instead of erroring #283 — search_code: invalid regex under regex: true silently returns empty instead of erroring

Install / watcher

• Watcher does not auto-reindex git-visible untracked file on Linux stdio MCP session (v0.6.0) #285 — Watcher does not auto-reindex git-visible untracked file on Linux stdio MCP session
• install.sh adds sh-style PATH manipulation to fish config #319 — install.sh adds sh-style PATH manipulation to fish config
• Add config key to disable file watcher #335 — Add config key to disable file watcher

UI / server

• Add a --host parameter for UI #229 — Add a --host parameter for UI
• v0.6.1 macOS arm64: --ui=true persists config but HTTP server never starts #350 — v0.6.1 macOS arm64: --ui=true persists config but HTTP server never starts

MCP / CLI behavior & messaging

• vendor/ directory indexed despite being excluded in root .gitignore #234 — vendor/ directory indexed despite being excluded in root .gitignore
• manage_adr (MCP/CLI) and the UI /api/adr endpoints use separate storage backends #256 — manage_adr (MCP/CLI) and the UI /api/adr endpoints use separate storage backends
• index_status returns project-not-found for project returned by list_projects #349 — index_status returns project-not-found for project returned by list_projects
• Add markdown memory.md #346 — Add markdown memory.md (session state file)

Docs

• Website outdated (agent support) #275 — Website outdated (agent support)
• Where can I find docs for configuration files? #359 — Where can I find docs for configuration files?
• [Question] How to measure gain/savings? #361 — [Question] How to measure gain/savings?

Acceptance

1. Each linked issue is either fixed, documented as intended behavior, or closed as out of scope with rationale.
2. Configuration file reference is fully documented (closes Where can I find docs for configuration files? #359).
3. Error messages are actionable — e.g. index_status and list_projects accept the same project selectors (closes index_status returns project-not-found for project returned by list_projects #349).

Why one task

These are individually low-severity but collectively erode confidence on first use. Treating them as one focused UX pass produces a coherent improvement instead of scattered drive-by fixes.

Added 2026-06-24 (triage)

Install / build-from-source

• brew installation for macos? #491 — brew installation for macOS
• codebase-memory-mcp dev (built from source via NixOS flake, github:DeusData/codebase-memory-mcp) #460 — codebase-memory-mcp dev build-from-source fails (NixOS flake)
• build from source fails on cachyos #589 — build from source fails on CachyOS

Watcher

• New files not detected without explicit re-index (watcher doesn't trigger for file creation) #520 — new files not detected without explicit re-index (watcher misses file creation)

UI / visualization

• UI binary crashes (clean exit) while rendering 3D graph #402 — UI binary crashes (clean exit) while rendering 3D graph
• 3D graph visualization freezes browser/system on repos with >10K nodes #498 — 3D graph visualization freezes browser/system on repos with >10K nodes
• Feature request: built-in graph visualization UI for indexed projects #564 — built-in graph visualization UI for indexed projects

Small features / UX

• AI not using the MCP as much as it should #509 — AI not using the MCP as much as it should (adoption)
• Feature Request: i18n support for web UI (Chinese localization) #553 — i18n support for web UI (Chinese localization)
• Project name strips non-ASCII (CJK) characters from path, resulting in truncated/unrecognizable names #571 — project name strips non-ASCII (CJK) characters from path
• File structure MCP tool #469 — File structure MCP tool

Added 2026-06-29 (triage)

Search/path UX

• fix(search): search_code returns 0 matches on macOS arm64 (graph index appears valid) #688 — search_code zero-match implementation tracker for macOS arm64 (relates search_code returns 0 matches for all patterns on macOS arm64 v0.8.1 (graph index healthy) #670)
• fix(search): search_code returns 0 matches when repo path contains spaces on macOS #687 — search_code space-in-path implementation tracker (relates search_code returns 0 matches when the indexed repo path contains a space (macOS) #679)
• search_code returns 0 matches when the indexed repo path contains a space (macOS) #679 — search_code returns zero matches when indexed repo path contains a space
• search_code returns 0 matches for all patterns on macOS arm64 v0.8.1 (graph index healthy) #670 — search_code returns zero matches for all patterns on macOS arm64

Ignore/worktree ergonomics

• index_repository ignores .git/info/exclude and core.excludesFile inside linked git worktrees #682 — linked worktrees ignore local/global git excludes during indexing
• .gitignore (non repo root) gaps and overrides #510 — nested .gitignore gaps and overrides
• Please make ALWAYS_SKIP_DIRS configurable by user #500 — make ALWAYS_SKIP_DIRS configurable by user
• Support .ignore files that act as a local override layer on top of .gitignore. #497 — support .ignore files as a local override layer

UI / install / docs

• 🔥中文视频教程 #665 — Chinese video tutorial / documentation request
• [ui] Graph canvas is black on high-DPI/large displays: EffectComposer MSAA render target exceeds GPU allocation (glRenderbufferStorageMultisample too large) due to uncapped setPixelRatio(dpr) #648 — graph canvas black on high-DPI / large displays
• Not a single folder wants to be indexed #655 — UI folder indexing does not start and expected log file is missing
• Completely unusable after botched upgrade #610 — unusable after botched upgrade
• [ui] Improve new index ergonomics #608 — improve new-index ergonomics
• installing again via install script is dark pattern: "rebuild index" message followed by delete index action #607 — reinstall script messaging/action around rebuilding index is misleading
• Windows: install.ps1 reports success but leaves MCP server unregistered (MotW + swallowed config errors + malformed taskkill) #697 — Windows install UX: MotW guidance, swallowed config errors, malformed taskkill filter

Added 2026-06-30 (triage)

Build / query / UI ergonomics

• scripts/build.sh / make fail under the Nix flake dev shell on macOS; cross-arch builds unsupported #705 — Nix flake dev shell false compiler-arch detection and macOS cross-arch build gap
• query_graph / search_graph return "project not found" inconsistently; DBs valid on disk but CLI looks up wrong inode #704 — search_graph / query_graph project lookup becomes inconsistent after fresh process
• [Windows] --ui=true starts but HTTP server never listens on v0.8.1 #707 — Windows graph UI HTTP server does not bind/listen
• index not working #708 — Windows indexing CLI and project-picker UX reports

Added 2026-07-09 (triage)

• Issue area labeler workflow fails on every issue — .github/issue-labeler.yml uses (?i) inline groups unsupported by JS RegExp #764 — issue area labeler workflow fails on every issue ((?i) inline groups unsupported by JS RegExp)
• discover: unify the exclusion predicate across all filesystem walkers #802 — discover: unify the exclusion predicate across all filesystem walkers
• ci: codeql-gate holds a runner slot for up to 45 min while polling #824 — ci: codeql-gate holds a runner slot for up to 45 min while polling

Added 2026-08-03 (triage)

• scripts/test.sh hangs indefinitely at the venue-parity contract when ImageMagick is installed (bash runs generate-sbom.py, 'import' becomes ImageMagick) #1384 — venue-parity test hangs when bash invokes Python imports as ImageMagick
• possibility to bypass specific file, filter based on file extension #1377 — configurable file and extension exclusions
• index_status returns ~26k tokens on a 11.8k-file repo (~8k on a 42-node repo) — payload dominated by deliberately-ignored files, with no way to trim #1356 — index_status emits an unboundedly expensive coverage payload
• Graph not updated when the working tree returns to clean (revert leaves false negatives) #1339 — watcher misses the working-tree transition back to clean
• index_repository --name is silently ignored when the repo sits outside the server's allowed root — project gets a path-derived name #1317 — explicit project name is lost across allowed-root/cache state transitions