agentleFS
tariknztariknz/irdashies/AGENTS.md

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.

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
  1. Very specific:

    Before making any non-trivial change, read docs/ARCHITECTURE_RULES.md.

    line 14
  2. Distinctive:

    Never commit directly to main: - always use feature branches and PRs.

    line 24
  3. Very specific:

    When opening a PR, follow .github/pull_request_template.md exactly.

    line 47
  4. Distinctive:

    After image for new UI. A prose description, Storybook link, or local file path does not satisfy this requirement.

    line 52
  5. Distinctive:

    Keep review media outside the repository and never commit screenshots just to host them.

    line 55
  6. Very specific:

    Use useTelemetryValuesRounded(key, precision) for float arrays where sub-threshold changes produce no visible or meaningful difference:

    line 105
  7. Distinctive:

    Create only when feature needs: historical data, complex calculations, shared state across feature components, or persistence across …

    line 135
  8. Distinctive:

    Keep scoped to feature - don't add to global exports unless multiple overlays need it.

    line 137
  9. Distinctive:

    Only use emojis in code comments, commit messages, or documentation if explicitly requested by the user

    line 206
  10. Distinctive:

    Always use Tailwind: - no custom CSS unless absolutely necessary.

    line 222
  11. Very specific:

    Create settings component in Settings/sections/

    line 282
  12. Very specific:

    Frontend MUST NOT import from ./app: - use IPC bridges only (type definitions in src/types/ are OK).

    line 295
  13. Very specific:

    Every component needs .stories.tsx:

    line 320
  14. Very specific:

    Add the config type to WidgetConfigMap in src/types/widgetConfigs.ts

    line 342
  15. Very specific:

    Create the manifest src/types/widgets/<id>.ts (defineWidgetManifest: name, menu label, enabled, layout, default config)

    line 343
  16. Very specific:

    Create the widget folder src/frontend/components/MyWidget/ with MyWidget.tsx, widget.ts (export default { id, component } satisfies …

    line 344
  17. Very specific:

    Create Settings/sections/MyWidgetSettings.tsx and add one line to WIDGET_SETTINGS in src/frontend/components/Settings/SettingsLoader.tsx

    line 345
  18. Distinctive:

    Do not add code comments unless the user explicitly requests them.

    line 375
  19. Distinctive:

    Use the project's logger utilities instead:

    line 406

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

irDashies - Development Guide

Project Overview

irDashies is an Electron-based iRacing overlay/dashboard app using React, TypeScript, Zustand, and Tailwind CSS.


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 errors

Clean 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 files

Pull 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 dashboard

State Management

Use CaseSolution
Cross-component, high-frequency (60 FPS telemetry)Zustand with custom equality
UI-only, single componentuseState
Configuration, callbacks, infrequent updatesReact 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 CaseHookPrecisionRationale
Track map positionuseTelemetryValuesRounded3dp0.1% of track length (~22m on Nords, ~5m on a 5km track) — sub-pixel on any rendered map
Position sorting (standings)useTelemetryValuesRounded3dpSame physical resolution; sufficient to distinguish order
Time delta display (0.1s)useTelemetryValuesRounded2dp10ms resolution, display is 100ms
Time interpolation (reference lap)useTelemetryValuesRounded4dpREFERENCE_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
  • CarSpeedsStore inputs — speed is derived from frame-to-frame deltas; rounding destroys the signal
  • FuelLevel / 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 hooks

Performance

  • memo() for components receiving props in high-frequency updates
  • useMemo() 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.tsx is a hand-drawn SVG, because Phosphor's FlagCheckered is not visible enough at badge size
  • 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.css with 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: StoreState with 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

  1. Define type in src/types/widgetConfigs.ts extending BaseWidgetSettings
  2. Create settings component in Settings/sections/
  3. Use BaseSettingsSection wrapper

Persistence Flow

User Changes → BaseSettingsSection → updateDashboard() → IPC → Disk → Reload on restart

IPC 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-coverage

Storybook

Every component needs .stories.tsx:

import { TelemetryDecorator } from '@irdashies/storybook';
const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
  decorators: [TelemetryDecorator()],
};
npm run storybook  # Port 6006

Development 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.

  1. Add the config type to WidgetConfigMap in src/types/widgetConfigs.ts
  2. Create the manifest src/types/widgets/<id>.ts (defineWidgetManifest: name, menu label, enabled, layout, default config)
  3. Create the widget folder src/frontend/components/MyWidget/ with MyWidget.tsx, widget.ts (export default { id, component } satisfies WidgetModule, or an array when the folder hosts several widgets), widgetRuntimeDefinition.ts and MyWidget.stories.tsx. Use lazyWidget from @irdashies/domain/lazyWidget for the component, as above: registration is eager, implementation loading is deferred until the widget renders.
  4. Create Settings/sections/MyWidgetSettings.tsx and add one line to WIDGET_SETTINGS in src/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.ts

Scripts

npm start              # Dev app
npm run storybook      # Component library
npm run test           # Tests
npm run lint           # ESLint
npm run package        # Create installer

Code 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

TechVersionTechVersion
React19Electron35.1
TypeScript5.9Vitest3.2
Zustand5Storybook10
Tailwind4.1Vite7.1

Architecture Principles

  1. Separation: Frontend (React) ↔ Bridge (IPC) ↔ Backend (Electron)
  2. Performance: Memoization, custom equality, lazy loading
  3. Type Safety: Strict TS, no any, guards at boundaries
  4. Tailwind-First: Minimal custom CSS
  5. 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:

ContextImport
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

IssueCheck
Store not updatingEquality comparator, memo deps, provider mounted
Settings not persistingmigrateConfig(), handleConfigChange(), IPC
Tailwind not workingRebuild, check theme.css, verify class names
Telemetry missingTelemetryProvider mounted, iRacing running, bridge connection

Tools: React DevTools, Zustand DevTools, Electron DevTools, Storybook

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.