openswarm/frontend/CLAUDE.md

frontend/CLAUDE.md

React 18 + TypeScript + webpack 5 + Redux. Entry: src/app/Main.tsx. Dev server on :3000 proxies REST and WebSocket to backend on :8324. See root CLAUDE.md for repo-wide constraints.

Run

• Dev (full stack): bash run.sh.
• Dev (frontend only): bash frontend/run.sh — runs npm install then npm run dev.
• No JS/TS test runner is wired up. Changes must be manually exercised in the running app before merging.

Key concepts

• Spatial dashboard — agents are draggable nodes on a canvas; layout + selection state lives in Redux.
• Settings draft persistence — AppSettings.dismissed_mcp_suggestions is a map of MCP id → ISO timestamp; preserve this shape when modifying settings serialization.
• Onboarding wizard (src/app/pages/Onboarding/) — 8-step agentic cursor walkthrough. Cursor offsets, fit-to-view, AC popup timing, and group-meta dedup were each delicate to land; verify visually after touching this code.
• Custom providers — AppSettings.custom_providers: CustomProvider[] supports any OpenAI-compatible endpoint (e.g. LM Studio).

Conventions

• TS only; no PropTypes.
• No eslint/prettier config — match nearby files.
• Onboarding-copy placeholders shaped like real API keys (sk-ant-api03-…) are already allowlisted in .gitleaks.toml. Reuse the existing placeholder rather than introducing new "example" tokens.
• MCP suggestion UI must surface only the vetted/default set — never expose the full upstream registry to users.

Pitfalls

• Direct LLM calls from the frontend bypass the backend's provider routing and MCP gate. Don't add them; route through /api/* instead.
• Webpack-dev-server hot reload occasionally loses WS state — full page reload after backend restarts.