From beb777bd546f930466a80a4352de4ab67392cfde Mon Sep 17 00:00:00 2001 From: SlayTheDragons <138079274+SlayTheDragons@users.noreply.github.com> Date: Thu, 30 Oct 2025 17:23:25 +1300 Subject: [PATCH] Add AGENTS.md for Claude Code, Gemini CLI and Codex (#1638) Adds AGENTS.md for Claude Code, Gemini CLI and Codex. --- ## Summary by cubic Adds AGENTS.md with clear guidelines for working in this Electron + React repo. It standardizes IPC patterns and React/TanStack Query usage to keep code consistent and secure. - **New Features** - Documents IPC architecture: renderer IpcClient, preload allowlist, host handlers, and throwing errors on failure. - Defines React integration: useQuery for reads, useMutation for writes, invalidate related queries, optional global state sync. - Notes security practices: avoid remote, validate/lock by appId on mutations. - Encourages descriptive names that mirror IPC channels and colocated tests/stories. --- AGENTS.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2e9392d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,25 @@ +# 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. + +## IPC architecture expectations +1. `src/ipc/ipc_client.ts` runs in the renderer. Access it via `IpcClient.getInstance()` and expose dedicated methods per IPC channel. +2. `src/preload.ts` defines the renderer allowlist. New IPC APIs must be added here. +3. `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`). +4. IPC handlers should `throw new Error("...")` on failure instead of returning `{ success: false }` style payloads. + +## React + IPC integration pattern +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. + +## General guidance +- 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.