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

[DeusData]

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

[DeusData]

Bug-tagged progress (2026-05-31) — the defect subset of this umbrella has been worked:

Fixed + closed:

• install.sh adds sh-style PATH manipulation to fish config #319 — installer wrote sh-syntax PATH into fish config → now emits fish_add_path
• index_status returns project-not-found for project returned by list_projects #349 — index_status not-found for a listed project → project names now always validator-safe
• v0.6.1 macOS arm64: --ui=true persists config but HTTP server never starts #350 — macOS --ui=true silent no-op → clear stderr message when binary lacks the embedded UI
• manage_adr (MCP/CLI) and the UI /api/adr endpoints use separate storage backends #256 — manage_adr (file) vs UI /api/adr (SQLite) split → unified on the store, with file→SQLite migration
• Watcher does not auto-reindex git-visible untracked file on Linux stdio MCP session (v0.6.0) #285 — watcher not auto-reindexing untracked files → verified fixed by the C watcher rewrite (regression test watcher_detects_new_file)
• search_code: invalid regex under regex: true silently returns empty instead of erroring #283 — search_code invalid regex silently empty → now returns an explicit error
• vendor/ directory indexed despite being excluded in root .gitignore #234 — vendor/ indexed despite root .gitignore → verified fixed + regression guard

Still open (tracked, not silently dropped):

• search_code: default regex=false treats | as literal pipe, not alternation (silent 0-match trap) #282 — regex=false treats | literally — by-design default; the "silent" half is addressed by search_code: invalid regex under regex: true silently returns empty instead of erroring #283, a 0-match metachar hint is a tracked enhancement
• search_code rejects paths containing & (ampersand) #272 — search_code rejects & in paths — security-sensitive (shared shell-arg validator); needs an audited fix or argv-exec rework, tracked

The remaining children (#229, #275, #335, #346, #359, #361) are UX/feature enhancements rather than defects.

[materwelonDhruv]

Perhaps you could use https://github.com/DeusData/codebase-memory-mcp/projects for this tracker? I haven't used it myself, but I've seen other large repos make use of it to automate tracking easily.

Let me know if you want me to delete this comment :)