irdashies
AGENTS.md272 starsChanged 16 days agoMITView on GitHub
irDashies is an Electron-based iRacing overlay/dashboard app using React, TypeScript, Zustand, and Tailwind CSS. Before making any non-trivial change, read docs/ARCHITECTURE_RULES.md. It contains the current hard rules for layering, telemetry subscriptions, stores, IPC/bridges, processors, storage, widgets, settings migration, native code, logging, security, performance, and testing — plus a Pre-PR checklist. The 2026 architecture review and phased implementation plan are preserved under docs/archive/architecture-2026/ as historical context. They are closed records, not active task lists, and do not need to be read…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- babysit-prSkill
- publish-prSkill
- release-notes-discordSkill
- release-notesSkill
- babysit-prSkill
- publish-prSkill
- release-notes-discordSkill
- release-notesSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
19 rules. About 0 are common, 9 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Before making any non-trivial change, read docs/ARCHITECTURE_RULES.md.
- Distinctive: line 24
Never commit directly to
main: - always use feature branches and PRs. - Very specific: line 47
When opening a PR, follow .github/pull_request_template.md exactly.
- Distinctive: line 52
After image for new UI. A prose description, Storybook link, or local file path does not satisfy this requirement.
- Distinctive: line 55
Keep review media outside the repository and never commit screenshots just to host them.
- Very specific: line 105
Use useTelemetryValuesRounded(key, precision) for float arrays where sub-threshold changes produce no visible or meaningful difference:
- Distinctive: line 135
Create only when feature needs: historical data, complex calculations, shared state across feature components, or persistence across …
- Distinctive: line 137
Keep scoped to feature - don't add to global exports unless multiple overlays need it.
- Distinctive: line 206
Only use emojis in code comments, commit messages, or documentation if explicitly requested by the user
- Distinctive: line 222
Always use Tailwind: - no custom CSS unless absolutely necessary.
- Very specific: line 282
Create settings component in Settings/sections/
- Very specific: line 295
Frontend MUST NOT import from
./app: - use IPC bridges only (type definitions in src/types/ are OK). - Very specific: line 320
Every component needs .stories.tsx:
- Very specific: line 342
Add the config type to WidgetConfigMap in src/types/widgetConfigs.ts
- Very specific: line 343
Create the manifest src/types/widgets/<id>.ts (defineWidgetManifest: name, menu label, enabled, layout, default config)
- Very specific: line 344
Create the widget folder src/frontend/components/MyWidget/ with MyWidget.tsx, widget.ts (export default { id, component } satisfies …
- Very specific: line 345
Create Settings/sections/MyWidgetSettings.tsx and add one line to WIDGET_SETTINGS in src/frontend/components/Settings/SettingsLoader.tsx
- Distinctive: line 375
Do not add code comments unless the user explicitly requests them.
- Distinctive: line 406
Use the project's logger utilities instead:
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.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
irDashies - Development Guide
Project Overview
irDashies is an Electron-based iRacing overlay/dashboard app using React, TypeScript, Zustand, and Tailwind CSS.
- Repo: https://github.com/tariknz/irdashies (fork)
- Branch:
main| License: MIT
Architecture Rules (read first)
Before making any non-trivial change, read docs/ARCHITECTURE_RULES.md. It contains the current hard rules for layering, telemetry subscriptions, stores, IPC/bridges, processors, storage, widgets, settings migration, native code, logging, security, performance, and testing — plus a Pre-PR checklist.
The 2026 architecture review and phased implementation plan are preserved under docs/archive/architecture-2026/ as historical context. They are closed records, not active task lists, and do not need to be read or referenced for unrelated work.
When ARCHITECTURE_RULES.md conflicts with anything in this file, the rules file wins for architecture concerns.
Git Workflow
Never commit directly to main - always use feature branches and PRs.
Branch Naming
feat/feature-name|fix/bug-description|chore/task|wip/experimental
Commit Format
<type>: <description>
# Examples: feat: add avg lap time column | fix: resolve linting errorsClean Feature Branches (cherry-pick)
git checkout main && git checkout -b feat/feature-clean
git cherry-pick <hash> # Full commit
git cherry-pick -n <hash> # Partial: then reset/checkout unwanted filesPull Requests
When opening a PR, follow .github/pull_request_template.md exactly. Fill in the Description and Screenshots (Before / After) sections, tick the matching Type of Change box, and only check Checklist items you've actually done — don't tick iRacing testing if you only verified in Storybook.
Every visual change requires screenshots. Show the updated UI to the user in the final response and upload actual screenshots as GitHub attachments in the PR body. Include Before / After images when changing existing UI, and at least an After image for new UI. A prose description, Storybook link, or local file path does not satisfy this requirement. Verify the uploaded images render in the PR.
Keep review media outside the repository and never commit screenshots just to
host them. If the installed GitHub CLI lacks --attach, check the current
official release and use an updated CLI (a verified portable release is fine)
before falling back to an authenticated browser upload. If uploads remain
blocked, keep the visual PR in draft, report the exact blocker, and do not claim
publication is complete until screenshots are attached.
Project Structure
src/
├── app/ # Electron main process
│ ├── bridge/ # IPC bridges (dashboard, iracingSdk)
│ ├── irsdk/ # iRacing SDK wrapper
│ └── storage/ # Dashboard persistence
├── frontend/ # React UI
│ ├── components/ # Widgets (Standings, Input, Settings, etc.)
│ ├── context/ # Zustand stores & React providers
│ └── utils/ # Shared utilities (colors, time)
└── types/ # Shared TypeScript types, widget configs, default dashboardState Management
| Use Case | Solution |
| Cross-component, high-frequency (60 FPS telemetry) | Zustand with custom equality |
| UI-only, single component | useState |
| Configuration, callbacks, infrequent updates | React Context |
Core Stores
// Telemetry (real-time)
const speed = useTelemetry('Speed', customComparator);
const playerSpeed = useTelemetryValue('Speed');
// Session (drivers, positions)
const drivers = useSessionDrivers();
const playerCarIdx = useDriverCarIdx();Telemetry Precision — useTelemetryValuesRounded
useTelemetryValues uses exact equality (===). Continuous float arrays like CarIdxLapDistPct change on every 60fps tick, causing subscriptions to fire every frame even when the UI doesn't need to update.
Use useTelemetryValuesRounded(key, precision) for float arrays where sub-threshold changes produce no visible or meaningful difference:
// Position on track — 3dp = ~0.5m resolution on a 5km track
const lapDistPcts = useTelemetryValuesRounded('CarIdxLapDistPct', 3);
// Time-based gaps displayed to 0.1s — 2dp = 10ms resolution
const estTimes = useTelemetryValuesRounded('CarIdxEstTime', 2);Precision guidelines by use case:
| Use Case | Hook | Precision | Rationale |
| Track map position | useTelemetryValuesRounded | 3dp | 0.1% of track length (~22m on Nords, ~5m on a 5km track) — sub-pixel on any rendered map |
| Position sorting (standings) | useTelemetryValuesRounded | 3dp | Same physical resolution; sufficient to distinguish order |
| Time delta display (0.1s) | useTelemetryValuesRounded | 2dp | 10ms resolution, display is 100ms |
| Time interpolation (reference lap) | useTelemetryValuesRounded | 4dp | REFERENCE_INTERVAL = 0.0025; 4dp keeps error <10ms |
| Smooth animation (throttle, steering) | useTelemetryValues | — | Full precision needed for 60fps feel |
| Speed calculations (delta between frames) | useTelemetryValues | — | Tiny frame deltas require full precision |
| Fuel calculations (divisor, threshold detection) | useTelemetryValues | — | Errors compound across lap |
Do not round:
- Input bar values (Throttle, Brake, Clutch, SteeringWheelAngle) — smooth animation is the feature
CarSpeedsStoreinputs — speed is derived from frame-to-frame deltas; rounding destroys the signalFuelLevel/SessionTime— used in threshold comparisons and projection calculations where errors accumulate
Specialized Stores
Create only when feature needs: historical data, complex calculations, shared state across feature components, or persistence across remounts.
Keep scoped to feature - don't add to global exports unless multiple overlays need it.
Existing: RelativeGapStore, LapTimesStore, CarSpeedsStore
Component Patterns
Structure
export const MyComponent = memo(({ prop }: Props) => {
const data = useSomeStore((s) => s.data); // 1. Hooks
const computed = useMemo(() => calc(data), [data]); // 2. Memoize
return <div className="flex items-center">{/* 3. Tailwind JSX */}</div>;
});
MyComponent.displayName = 'MyComponent';File Organization
ComponentName/
├── ComponentName.tsx
├── ComponentName.stories.tsx
├── components/ # Sub-components
└── hooks/ # Component-specific hooksPerformance
memo()for components receiving props in high-frequency updatesuseMemo()for expensive calculations- Custom equality comparators for Zustand array selectors
Widget Registration
Widgets register themselves. WIDGET_MAP (WidgetIndex.tsx), the settings menu, WIDGET_NAMES and defaultDashboard are built from two files per widget:
// src/types/widgets/mywidget.ts — main-safe data
export default defineWidgetManifest({
id: 'mywidget',
name: 'My Widget',
enabled: false,
layout: { x: 0, y: 0, width: 300, height: 100 },
config: { background: { opacity: 80 } },
});
// src/frontend/components/MyWidget/widget.ts — component
import { lazyWidget } from '@irdashies/domain/lazyWidget';
import type { WidgetModule } from '@irdashies/domain';
export default {
id: 'mywidget',
component: lazyWidget(() =>
import('./MyWidget').then((module) => ({ default: module.MyWidget }))
),
} satisfies WidgetModule;UI Design Rules
NEVER use emojis in frontend or client-visible UI components.
- Emojis are not allowed in any JSX, component text, labels, buttons, tooltips, or user-facing strings
- For icons, use the Phosphor icon pack included in the project
- Exception: the finished-car checkered flag in
DriverStatusBadges.tsxis a hand-drawn SVG, because Phosphor'sFlagCheckeredis not visible enough at badge size
- Exception: the finished-car checkered flag in
- Only use emojis in code comments, commit messages, or documentation if explicitly requested by the user
Using Phosphor Icons
import { Icon } from '@phosphor-icons/react';
// Example usage
<Icon.Flag size={16} weight="fill" className="text-amber-300" />
<Icon.CheckCircle size={20} />Tailwind CSS
Always use Tailwind - no custom CSS unless absolutely necessary.
- Theme:
theme.csswith CSS variables - Font: Lato | Version: 4.1
Common Patterns
// Overlay background with variable opacity
<div className="bg-slate-800/(--bg-opacity) rounded-sm p-2 text-white">
// State-based styling
<tr className={['odd:bg-slate-800/70 even:bg-slate-900/70',
!onTrack ? 'text-white/60' : '', isPlayer ? 'text-amber-300' : ''].join(' ')}>
// Scrollable content
<div className="flex flex-col h-full">
<div className="flex-none">Header</div>
<div className="flex-1 overflow-y-auto min-h-0">Content</div>
</div>Colors
import { getTailwindStyle, getColor } from '@irdashies/utils/colors';TypeScript
Path Aliases
import { useTelemetryStore } from '@irdashies/context';
import { formatTime } from '@irdashies/utils/time';
import type { DashboardLayout } from '@irdashies/types';Naming Conventions
- Props:
ComponentNameProps - Settings:
WidgetNameSettings extends BaseWidgetSettings - Store state:
StoreStatewith data + actions - Types:
type SessionType = 'Practice' | 'Qualifying' | 'Race'
Best Practices
- Strict mode enabled, no
any - Optional chaining:
telemetry?.SessionTime?.value?.[0] - Type guards at boundaries
Widget Settings
Pattern
- Define type in
src/types/widgetConfigs.tsextendingBaseWidgetSettings - Create settings component in
Settings/sections/ - Use
BaseSettingsSectionwrapper
Persistence Flow
User Changes → BaseSettingsSection → updateDashboard() → IPC → Disk → Reload on restartIPC Bridge Architecture
Frontend MUST NOT import from ./app - use IPC bridges only (type definitions in src/types/ are OK).
// Bridge pattern
interface MyBridge {
getData: () => Promise<Data>;
onDataUpdated: (cb: (data: Data) => void) => () => void;
}Testing
- Runner: Vitest | Files:
*.spec.ts(x)| DOM: @testing-library/react
npm run test # With coverage
npm run test -- --no-coverageStorybook
Every component needs .stories.tsx:
import { TelemetryDecorator } from '@irdashies/storybook';
const meta: Meta<typeof MyComponent> = {
component: MyComponent,
decorators: [TelemetryDecorator()],
};npm run storybook # Port 6006Development Tasks
Adding a Widget
Widgets are auto-discovered from their manifest and widget.ts; only the config type and the settings page are listed centrally.
- Add the config type to
WidgetConfigMapinsrc/types/widgetConfigs.ts - Create the manifest
src/types/widgets/<id>.ts(defineWidgetManifest: name, menu label, enabled, layout, default config) - Create the widget folder
src/frontend/components/MyWidget/withMyWidget.tsx,widget.ts(export default { id, component } satisfies WidgetModule, or an array when the folder hosts several widgets),widgetRuntimeDefinition.tsandMyWidget.stories.tsx. UselazyWidgetfrom@irdashies/domain/lazyWidgetfor the component, as above: registration is eager, implementation loading is deferred until the widget renders. - Create
Settings/sections/MyWidgetSettings.tsxand add one line toWIDGET_SETTINGSinsrc/frontend/components/Settings/SettingsLoader.tsx
Standard single-value settings are described once in the manifest's properties (label, limits, options), keyed by config path. On the settings page, wrap the rows in <SettingProps widget="mywidget" ...> and render them with const SettingProp = settingPropFor('mywidget'), then <SettingProp path="background.opacity" />. TypeScript checks both sides against the widget's config type: a path that isn't in the config, or a spec that doesn't fit the value (for example a slider on a boolean), fails to compile.
Removing a widget: delete those pieces; widgetRegistry.spec.ts and TypeScript flag any leftovers (the derived maps are only checked by the spec).
Adding a Hook
// src/frontend/context/shared/useMyHook.tsx
export const useMyHook = () => {
/* ... */
};
// Export from context/index.tsScripts
npm start # Dev app
npm run storybook # Component library
npm run test # Tests
npm run lint # ESLint
npm run package # Create installerCode Quality
- Do not add code comments unless the user explicitly requests them. Prefer clear names and straightforward code.
- ESLint before committing
- Prettier: single quotes, 80 chars, trailing commas (ES5)
Key Technologies
| Tech | Version | Tech | Version | |
| React | 19 | Electron | 35.1 | |
| TypeScript | 5.9 | Vitest | 3.2 | |
| Zustand | 5 | Storybook | 10 | |
| Tailwind | 4.1 | Vite | 7.1 |
Architecture Principles
- Separation: Frontend (React) ↔ Bridge (IPC) ↔ Backend (Electron)
- Performance: Memoization, custom equality, lazy loading
- Type Safety: Strict TS, no
any, guards at boundaries - Tailwind-First: Minimal custom CSS
- Feature Isolation: Scoped stores, co-located code
Logging
Never use console.log / console.warn / console.error directly — ESLint enforces no-console.
Use the project's logger utilities instead:
| Context | Import |
Main process (src/app) | import logger from './logger' (electron-log) |
Frontend (src/frontend) | import logger from '@irdashies/utils/logger' |
The frontend logger forwards messages to the main process via IPC for file persistence and also logs to the browser console for DevTools visibility.
// Main process
import logger from './logger';
logger.info('SDK connected');
logger.error('Bridge failed', err);
// Frontend
import logger from '@irdashies/utils/logger';
logger.info('Dashboard loaded');
logger.warn('Missing widget config', widgetId);Available levels: debug, info, warn, error
Debugging
| Issue | Check |
| Store not updating | Equality comparator, memo deps, provider mounted |
| Settings not persisting | migrateConfig(), handleConfigChange(), IPC |
| Tailwind not working | Rebuild, check theme.css, verify class names |
| Telemetry missing | TelemetryProvider mounted, iRacing running, bridge connection |
Tools: React DevTools, Zustand DevTools, Electron DevTools, Storybook
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.

