AntanI / src
CLAUDE.md2 starsChanged 10 days agoMITView on GitHub
The React + TypeScript + Vite frontend is a thin view over Rust state. It renders the sidebar and workspace and calls Tauri commands; all persistence and process lifecycle live in Rust. If logic isn't purely presentational, it belongs on the Rust side, not here. - Strict TypeScript. No any, no @ts-ignore / @ts-expect-error. Fix types properly. - Components stay small (~200 lines max). Split when they grow. - No <StrictMode>. main.tsx renders <App /> bare, on purpose. StrictMode's dev-only…
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- adding-tauri-commandSkill
- prepare-releaseSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Do not add tailwind.config.js or a PostCSS pipeline — that's the v3 way and will fight the v4 setup.
- Distinctive: line 30
Never duplicate the palette in Rust or a component.
- Very specific: line 41
Don't re-enable them or litter per-line biome-ignore comments.
- Very specific: line 76
Do not add React component render tests, DOM-interaction tests, or Tauri invoke mocks.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Frontend — Agent Guide (src/)
Why this exists
The React + TypeScript + Vite frontend is a thin view over Rust state. It renders the sidebar and workspace and calls Tauri commands; all persistence and process lifecycle live in Rust. If logic isn't purely presentational, it belongs on the Rust side, not here.
Rules
- Strict TypeScript. No
any, no@ts-ignore/@ts-expect-error. Fix types properly. - Components stay small (~200 lines max). Split when they grow.
- No
<StrictMode>.main.tsxrenders<App />bare, on purpose. StrictMode's dev-only double-invoke of effects would spawn and then immediately tear down real OS resources (terminal PTYs, and later embedded webviews) — those aren't idempotent React state, so the double-mount actively breaks them. Don't re-add it. - Tailwind v4, no config file. Styling is
@import "tailwindcss"inindex.cssplus utility classes, wired through the@tailwindcss/viteplugin. Do not addtailwind.config.jsor a PostCSS pipeline — that's the v3 way and will fight the v4 setup. The color theme is defined once as@themetokens inindex.css(the single source for chrome colors, e.g.bg-sidebar,text-foreground). Biome's CSS parser rejects@themeas an unknown at-rule, sobiome.jsonsetscss.parser.tailwindDirectives— that flag exists only to teach the linter v4 syntax, not to relax or swap tooling. - No magic numbers. Ports, timeouts, limits, and the project color palette
are named constants. The palette lives in exactly one place (
src/lib) and is the single source of truth — Rust just stores whatever hex string it receives. Never duplicate the palette in Rust or a component. - IPC conventions. Tauri v2 maps camelCase JS argument keys to snake_case Rust
parameters, so call commands with camelCase (e.g.
orderedIds). Mutating commands return the full updated state; adopt that return value instead of optimistically mutating local state — it keeps the UI drift-free. Keep the TS types mirroring the Rust structs (camelCase). - Accessibility rules are intentionally relaxed. Biome's
noStaticElementInteractionsanduseKeyWithClickEventsare off inbiome.jsonon purpose: this is a single-user local desktop tool, not a public web page. Clickable/draggable rows and the color-picker backdrop don't need ARIA roles or duplicated keyboard handlers (project switching already has Cmd+1..9). Don't re-enable them or litter per-linebiome-ignorecomments. Revisit only if genuinely public-facing web content is ever added.
Tauri / WKWebView platform notes
- No HTML5 drag API.
draggable,dataTransfer,ondrop, and window-leveldroplisteners (even with the capture flag) silently fail in Tauri's WKWebView on macOS. Use pointer events for all in-app drag interactions, exactly asuseDragReorderdoes. For drag state that must be shared across distant components (e.g. sidebar → terminal), a plain mutable module-level object is the right primitive — no React state, no context (seesrc/lib/fileDrag.ts). For drag ghosts / visual feedback, manipulate the DOM directly and imperatively (create onpointerdown, move onpointermove, remove onpointerup); avoid routing this through React renders. Always calle.preventDefault()onpointerdownand setdocument.body.style.userSelect = "none"while a drag is live to prevent text selection bleed-through into xterm. - Popovers that close on outside-click need
e.stopPropagation()on the trigger.ColorPicker,ConfirmPopover, andContextMenuall close themselves via awindow.addEventListener("click", ...)added inuseEffect. If the button that opens one of them doesn't stop propagation, that same click keeps bubbling towindowand closes the popover in the same tick it opened — before it ever paints. It looks like the popover "doesn't render" (or, worse, silently no-ops) rather than flashing open; there's no console error.TabChip's context-menu items get this for free because their menu container already stops propagation; any trigger button that isn't inside such a container must calle.stopPropagation()itself (see the color swatches inSettingsPage.tsx).
Testing: what, and why
Vitest tests pure logic in src/lib only — e.g. path→name parsing and palette
cycling — because that logic has real edge cases and is deterministic. These tests
assert behavior (inputs → outputs), not internals.
Do not add React component render tests, DOM-interaction tests, or Tauri
invoke mocks. They are brittle, break on harmless markup changes, and cost more
to maintain than they catch in a one-person tool. Verify the UI by running the app.
The coverage gate is global (90%), so a thin Tauri wrapper file with no logic
worth testing drags the whole ratio down instead of just sitting at 0%. Name
any src/lib file that's purely invoke/listen/plugin-API wrapping with an
.ipc.ts suffix (e.g. api.ipc.ts, notifications.ipc.ts) — vitest.config.ts
excludes src/lib/**/*.ipc.ts from coverage by that pattern, so new wrapper
files are excluded automatically and can't silently break CI the way an
unlisted file would.
Agent waiting detection lives in src/lib/agentStatus.ts because each CLI has
different permission and question UI. Keep its patterns provider-specific and
high-signal: broad words such as “confirm”, “trust”, or “press enter” regularly
appear in ordinary assistant output and cause false waiting notifications. Add
pure-logic fixtures for both recognized prompts and provider mismatches whenever
a CLI changes its wording.
Agent composers use Ctrl+J for soft-newlines. Do not send CSI-u Shift+Enter
through xterm/WKWebView: Codex can interpret it as its clipboard-image action.
Plain shells still need Ctrl-V + Ctrl-J. Keep both physical Shift+Enter handling
and injectable multiline text routed through softNewlineForKind. Physical
Shift+Enter goes through shiftEnterSequence, which sends Ctrl-V only when the
PTY's foreground process is a shell (shellInForeground from the Rust
running poll): an agent launched by hand in a terminal tab reads Ctrl-V as
clipboard paste.
Injected prompts reach agent tabs wrapped in bracketed-paste markers
(ESC[200~ … ESC[201~), the same bytes xterm sends for a Cmd+V paste. Don't
write raw multi-line text instead: macOS delivers a large PTY write in chunks,
and Claude Code guesses paste boundaries from those chunks, keeping only a
fragment behind a "paste again to expand" hint. All three agent CLIs enable
bracketed paste mode (DECSET 2004). Plain shells keep the unwrapped
Ctrl-V + Ctrl-J encoding.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

