Repository Agent Guide

Project context

This is an Electron application with a secure IPC boundary.
Frontend is a React app that uses TanStack Router (not Next.js or React Router).
Data fetching/mutations should be handled with TanStack Query when touching IPC-backed endpoints.

src/ipc/ipc_client.ts runs in the renderer. Access it via IpcClient.getInstance() and expose dedicated methods per IPC channel.
src/preload.ts defines the renderer allowlist. New IPC APIs must be added here.
src/ipc/ipc_host.ts registers handlers that live in files under src/ipc/handlers/ (e.g., app_handlers.ts, chat_stream_handlers.ts, settings_handlers.ts).
IPC handlers should throw new Error("...") on failure instead of returning { success: false } style payloads.

When creating hooks/components that call IPC handlers:

Wrap reads in useQuery, providing a stable queryKey, async queryFn that calls the relevant IpcClient method, and conditionally use enabled/initialData/meta as needed.
Wrap writes in useMutation; validate inputs locally, call the IPC client, and invalidate related queries on success. Use shared utilities (e.g., toast helpers) in onError.
Synchronize TanStack Query data with any global state (like Jotai atoms) via useEffect only if required.

Favor descriptive module/function names that mirror IPC channel semantics.
Keep Electron security practices in mind (no remote, validate/lock by appId when mutating shared resources).
Add tests in the same folder tree when touching renderer components.

Use these guidelines whenever you work within this repository.