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
- onyx-dot-app/onyxword for word, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 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.
- AGENTS.mdAGENTS.md
- backend/AGENTS.mdAGENTS.md
- documentation/AGENTS.mdAGENTS.md
- web/AGENTS.mdAGENTS.md
- docs-writingSkill
- feature-mapSkill
- merge-dependabot-prsSkill
- onyx-craft-devSkill
- onyx-dev-stackSkill
- playwright-e2e-testsSkill
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
- Distinctive: line 11
Before hand-rolling any component or screen, check for a matching component:
≈ “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
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 othercomponents/*first. - Only web has it? Web (Opal
web/lib/opal/src/, orweb/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 theport-web-component-to-mobileskill) 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 size | web (Tailwind step) | mobile (px-named token) |
| 8px | p-2 | p-8 |
| 16px | p-4 | p-16 |
| 24px | p-6 | p-24 |
Rules:
- Never copy a web spacing class number to mobile. Translate a web Tailwind step
N→ mobileN × 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(CenteredContentowns the centered screen gutter). A new screen/empty-state composes an existing shell instead of hardcodingpx-24.
Text, inputs, icons, colors
- Render all text via
@/components/ui/textText(font/colorstring-enum props). Never use React Native'sText(including in tests).react-nativeTextInputis unrelated and fine, but prefer@/components/ui/text-inputfor fields. - Icons are default-exported from
@/icons/*, rendered via@/components/ui/iconIcon(<Icon as={SvgFoo} size={…} className="text-text-…" />). - Colors: use Onyx semantic classes (
bg-background-*,text-text-*,border-border-*). They resolve at runtime through thevars()provider inapp/_layout.tsx(light/dark from@onyx-ai/shared/native). Nodark:modifier; no raw Tailwind colors.
HTTP, data, navigation
- HTTP:
@/api/clientapiFetch<T>(injects bearer, normalizes errors toApiError).getBaseUrl()already appends the/apiprefix, so paths are bare:apiFetch("/chat/..."),apiFetch("/me"). The streaming chat call is the one exception:api/chat/stream.tsusesexpo/fetch, because only its response exposes a readablebodyon 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 viaNON_PERSISTED_KEY_PREFIXESin@/query/client.ts. - Navigation: expo-router. Route groups are path-transparent (
app/(app)/index.tsx=/). Auth routing is imperative incomponents/auth/AuthGate.tsx(pure logic inauthRoute.ts). The nav surface is a foldable sidebar overlay (Portal-based,components/sidebar), not a tab bar. UseuseGlobalSearchParamsin layouts,useLocalSearchParamsin screens.
Tests
- Runner:
jest-expo. Tests live in__tests__/(src/**/__tests__/**/*.test.ts?(x)). Gate withbun 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, thenjest.mock(...)(babel hoists the mock; this also satisfiesimport/first). - Native mocks are centralized: MMKV self-mocks,
expo-secure-storemanual mock in__mocks__/, resets injest.setup.ts. - A generic fn like
apiFetch<T>makesjest.mocked()infernever— cast it:apiFetch as unknown as Mock<(p: string, i?: ApiFetchInit) => Promise<unknown>>(Mockfromjest-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/nativeis 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, anddistbuild 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/sharedfor design tokens and neutral contracts. - Editing the shared package requires rebuilding its
dist(bun run buildinweb/lib/shared); the mobilefile:dep consumesdist. Web jest resolves it fromsrcvia amoduleNameMapper. - Mobile's
preinstallhook buildsweb/lib/shared'sdist(a git-ignored artifact) before bun links thefile:dep, so a freshbun installcan't hit an unresolved@onyx-ai/shared/dist. It must bepreinstall, notpostinstall: bun's link farm only includesdistif it exists at link time. Active token/source edits still hot-rebuild viabun run devinweb/lib/shared.
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.

