Switch Bay

An agentic second brain you grow. Feed it your notes, docs, and sources; capable agents curate them into expert knowledge graphs that compound — richer every session, owned and guided by you. Route it. Grow it. Use it.

Switch Bay turns a folder of raw material — notes, documents, sources, tasks — into a private, compounding knowledge graph, and gives you a cockpit where AI agents work over it: chat grounded in what you know, curate captured material into linked wiki pages, fan out parallel agents, and render rich answers as documents. It runs entirely on your machine, against whatever models you choose, and nothing leaves unless you send it.

• Local & private — two processes and your files. No cloud, no accounts; your data and API keys stay on your machine.
• Bring your own models — hosted APIs (Anthropic, xAI Grok, OpenAI, Gemini), subscription coding CLIs (Claude Code, Grok Build, Codex, Copilot), or fully-local models (llama.cpp / Ollama). Mix them per task with a model ladder.
• Knowledge that compounds — capture → curate → graph. Every session leaves the graph richer, so the next one starts smarter. Agents propose wiki edits; a stronger reviewer (and you) keep them honest.
• Two cockpits — Power mode (3-column: browser · tabs · rail) and Zen mode (think at the graph). Same data, your choice.
• Custom tabs — describe the view you want and an agent builds it just-in-time over your own data. Pin the keepers (globally or per workspace); throw the rest away.

New here? Read docs/concepts-and-data-flow.md — how Switch Bay is put together in one read: the core vocabulary (Workspace → Thread → Run → Turn), the runtime shape, and the data flows behind the things you do most.

A workspace is any folder with a curiosity-engine-shaped layout (vault/ raw sources + wiki/ docs & graph); Switch Bay degrades gracefully on folders that don't have one yet.

Install (one command)

On a fresh clone, this checks prerequisites (auto-installs uv; tells you how to get Node + pnpm if missing), installs deps, builds the frontend, and registers the always-on service:

make install                 # lean install — recall runs FTS-only
make install SEMANTIC=1      # + local semantic embeddings (fastembed/ONNX, ~150 MB)

Then open http://127.0.0.1:8765 and install it as an app. You can add local semantic embeddings later with make sync-semantic.

Prerequisites: git, Node.js + pnpm (the installer guides you if they're missing), and uv (auto-installed). Python ≥3.11 is provisioned by uv. The base install is ~50 MB of Python deps; SEMANTIC=1 adds ~150 MB (fastembed, no PyTorch). Semantic recall is fail-soft — without it, recall_rail degrades to full-text search only. For byte-exact interop with a curiosity-engine vault index you can instead use the PyTorch backend: make sync-semantic-torch.

Run (dev)

One-time install:

make sync           # uv sync (base Python deps; add `make sync-semantic` for embeddings)
make sync-frontend  # pnpm install in frontend/

Two processes. In one terminal:

WORKSPACE=/path/to/workspace make dev-daemon

In another:

make dev-frontend

Then open the URL vite prints (default http://localhost:5173). Vite proxies /api and /ws to the daemon on :8765.

Test

make test    # hermetic unit suite (tests/unit) — pytest, no daemon needed
make check   # unit tests + daemon import smoke + frontend typecheck/build
make e2e     # Playwright browser smoke (needs the dev servers running)

CI (.github/workflows/ci.yml) runs the unit suite + import smoke and the frontend build on every push/PR. The live-daemon round-trip in tests/integration/ is run by hand (it needs a running daemon + a real workspace).

Install as an app

For everyday use, run it as an installable PWA over an always-on local daemon:

make install-service   # builds the frontend + registers a launchd agent

The daemon then serves the built app at http://127.0.0.1:8765; open it and install it (dock icon + standalone window). Closing the window does not stop work — runs live in the daemon. make stop / make restart / make status manage the service; make uninstall-service removes it.

Iterating without quitting the PWA

While developing against the dock app, keep the window open and run:

make refresh              # restart daemon; open PWA auto-reloads
make refresh BUILD=1      # rebuild frontend/dist, then restart

The client polls GET /api/health on loopback and reloads when the daemon’s boot_id or the built frontend/dist mtime changes — so you don’t need to quit and reopen the PWA after each restart.

Why no switchbay console script? uv-managed venvs on macOS get the UF_HIDDEN flag re-applied to their files asynchronously (LaunchServices / Spotlight). Python ≥3.13's site.py skips hidden .pth files, breaking editable installs racily. We invoke via python -m switchbay with PYTHONPATH=src instead — see [tool.uv] package = false in pyproject.toml.

More

• docs/concepts-and-data-flow.md — the map: concepts + data flows.
• docs/known-issues.md — rough edges + deliberate deferrals in this release.
• docs/THIRD-PARTY-NOTICES.md — third-party attributions.
• docs/license-risk-report.md — dependency-license review.
• CLAUDE.md — orientation for AI coding sessions.