agentleFS
onyx-dot-apponyx-dot-app/onyx-foss/mobile/AGENTS.md

onyx-foss / mobile

AGENTS.md320 starsChanged 8 days agoMITView on GitHub

Source of truth for AI agents working in mobile/ (the Onyx React Native + Expo app). It complements but does not inherit web/AGENTS.md: the mobile app has no DOM, uses NativeWind (not web Tailwind), expo-router, and RN primitives — so web rules about HTML/CSS, useSWR, Opal components, etc. do not apply here. Only the cross-platform design-token vocabulary is shared, via @onyx-ai/shared. Before hand-rolling any component or screen, check for a matching component: - Mobile already has it? Reuse it —…

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. onyx-dot-app/onyx★ 33k100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • 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 repository10 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 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.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before hand-rolling any component or screen, check for a matching component:

    line 11

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

Mobile App Standards (React Native + Expo)

Source of truth for AI agents working in mobile/ (the Onyx React Native + Expo app). It complements but does not inherit web/AGENTS.md: the mobile app has no DOM, uses NativeWind (not web Tailwind), expo-router, and RN primitives — so web rules about HTML/CSS, useSWR, Opal components, etc. do not apply here. Only the cross-platform design-token vocabulary is shared, via @onyx-ai/shared.

Building UI — reuse before you build

Before hand-rolling any component or screen, check for a matching component:

  • Mobile already has it? Reuse it — scan components/ui/*, the shell layouts (components/{settings,sidebar,auth,chat}), @/icons/*, and other components/* first.
  • Only web has it? Web (Opal web/lib/opal/src/, or web/src/refresh-components/) is the design source of truth. Don't hand-roll a divergent lookalike — STOP and ask whether to port it (pixel/behaviour-exact, via the port-web-component-to-mobile skill) or compose existing primitives.

Mirror the web counterpart's layout/spacing/color/interaction as closely as the platform allows; document any deliberate divergence.

Spacing: the class number is PIXELS (not web's Tailwind step scale)

The single biggest footgun when porting from web. Mobile spacing classes resolve to pixels equal to the class number: px-24 = 24px, gap-8 = 8px, h-12 = 12px. This comes from the shared design tokens (web/lib/shared/tokens/size.json spacing-block-*, defined in rem) converted in style-dictionary.config.mjs (toPx = rem × 16) and emitted as the NativeWind spacing scale (@onyx-ai/shared/nativewind-theme). RN can't use rem/var() for dimensions, so dimensions are baked to px.

Web is different: web uses Tailwind's default step scale, where p-6 = step 6 = 1.5rem = 24px. Same physical scale, different naming:

Physical sizeweb (Tailwind step)mobile (px-named token)
8pxp-2p-8
16pxp-4p-16
24pxp-6p-24

Rules:

  • Never copy a web spacing class number to mobile. Translate a web Tailwind step N → mobile N × 4 (px), or just use the px you actually want — on mobile the number is px.
  • Stick to the token keys that exist on the scale (0,2,4,6,8,10,12,16,20,24,28,32,36,40,44,48,…). A non-token key (e.g. p-3) falls through to Tailwind's default rem scale — avoid it.
  • Centralize recurring spacing in a layout primitive; don't repeat it per screen. Screen gutters live in shells: components/auth/AuthScreenShell.tsx, components/chat/ChatScreen.tsx (CenteredContent owns the centered screen gutter). A new screen/empty-state composes an existing shell instead of hardcoding px-24.

Text, inputs, icons, colors

  • Render all text via @/components/ui/text Text (font/color string-enum props). Never use React Native's Text (including in tests). react-native TextInput is unrelated and fine, but prefer @/components/ui/text-input for fields.
  • Icons are default-exported from @/icons/*, rendered via @/components/ui/icon Icon (<Icon as={SvgFoo} size={…} className="text-text-…" />).
  • Colors: use Onyx semantic classes (bg-background-*, text-text-*, border-border-*). They resolve at runtime through the vars() provider in app/_layout.tsx (light/dark from @onyx-ai/shared/native). No dark: modifier; no raw Tailwind colors.

HTTP, data, navigation

  • HTTP: @/api/client apiFetch<T> (injects bearer, normalizes errors to ApiError). getBaseUrl() already appends the /api prefix, so paths are bare: apiFetch("/chat/..."), apiFetch("/me"). The streaming chat call is the one exception: api/chat/stream.ts uses expo/fetch, because only its response exposes a readable body on React Native.
  • Server state: TanStack Query, keyed by serverUrl (@/api/query-keys) so switching instances never serves a prior backend's data. The cache persists to unencrypted MMKV — any PII key (chat content, identity) must be excluded via NON_PERSISTED_KEY_PREFIXES in @/query/client.ts.
  • Navigation: expo-router. Route groups are path-transparent (app/(app)/index.tsx = /). Auth routing is imperative in components/auth/AuthGate.tsx (pure logic in authRoute.ts). The nav surface is a foldable sidebar overlay (Portal-based, components/sidebar), not a tab bar. Use useGlobalSearchParams in layouts, useLocalSearchParams in screens.

Tests

  • Runner: jest-expo. Tests live in __tests__/ (src/**/__tests__/**/*.test.ts?(x)). Gate with bun run typecheck, bun run lint, bunx jest.
  • Import jest globals from @jest/globals (describe/it/expect/jest/beforeEach) — the TS config carries no ambient test types. Put all imports first, then jest.mock(...) (babel hoists the mock; this also satisfies import/first).
  • Native mocks are centralized: MMKV self-mocks, expo-secure-store manual mock in __mocks__/, resets in jest.setup.ts.
  • A generic fn like apiFetch<T> makes jest.mocked() infer never — cast it: apiFetch as unknown as Mock<(p: string, i?: ApiFetchInit) => Promise<unknown>> (Mock from jest-mock).
  • Don't import reanimated-pulling barrels in unit tests. @/components/sidebar (→ Sidebar.tsx → reanimated) crashes under jest ("Worklets not initialized"). Import leaf components directly (e.g. @/components/sidebar/SidebarTab) to keep a component unit-testable.

Shared package (@onyx-ai/shared)

  • Holds cross-platform design tokens + neutral contracts/types/utils. @onyx-ai/shared/native is RN-only (NativeWind theme/vars/typography); cross-platform types go in /contracts, never /native.
  • Grow it extract-on-proven-reuse, not upfront. The mobile chat layer is written natively in mobile/src/chat/ (NOT shared) by decision. The NDJSON parser, message tree, processRawChatHistory, and the chat/streaming/file contracts exist in both web and mobile, and nothing chat-related goes into @onyx-ai/shared. Reason: sharing even the small parser needs a shared util, a web re-point, a jest module mapper, and dist build coupling, which costs more than the duplicated code. The backend NDJSON framing and message threading are stable, so drift risk is low; extract again if drift occurs. Keep @onyx-ai/shared for design tokens and neutral contracts.
  • Editing the shared package requires rebuilding its dist (bun run build in web/lib/shared); the mobile file: dep consumes dist. Web jest resolves it from src via a moduleNameMapper.
  • Mobile's preinstall hook builds web/lib/shared's dist (a git-ignored artifact) before bun links the file: dep, so a fresh bun install can't hit an unresolved @onyx-ai/shared/dist. It must be preinstall, not postinstall: bun's link farm only includes dist if it exists at link time. Active token/source edits still hot-rebuild via bun run dev in web/lib/shared.

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.