threadbase-mobile
AGENTS.md4 starsChanged 2 days agoMITView on GitHub
Keep this file to repository-specific behavior and safeguards. Agent tooling is documented in docs/agents/tooling.md; operational diagnosis belongs in docs/troubleshooting.md. The mobile client absorbs streamer
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 repository14 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-providerSkill
- expo-local-shipSkill
- integration-by-batchesSkill
- setup-cloudflaredSkill
- ship-expo-cloudSkill
- ship-fastlaneSkill
- add-provider-mobileSkill
- expo-local-shipSkill
- integration-by-batches-mobileSkill
- setup-cloudflaredSkill
- ship-expo-cloudSkill
- ship-fastlaneSkill
- threadbase-designSkill
The file
We split this AGENTS.md into the rules it gives an agent
12 rules. About 0 are common, 2 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
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
- Distinctive: line 3
Keep this file to repository-specific behavior and safeguards.
- Very specific: line 8
Before committing JavaScript or TypeScript, run npx eslint on the staged JS/TS files.
- Very specific: line 20
Never use emoji as UI icons.
- Very specific: line 21
Every new components//*.tsx file requires a colocated *.stories.tsx in the same commit.
- Very specific: line 25
When package.json or package-lock.json changes, run pod install in ios/ and keep package.json, package-lock.json, and ios/Podfile.lock …
- Very specific: line 26
Treat checksum-only drift for ExpoModulesCore, ExpoWidgets, hermes-engine, and RNSentry as path noise.
- Very specific: line 27
Every physical iOS device build/install must use scripts/dev-device.sh.
- Very specific: line 31
Use /expo-local-ship for ordinary ship, TestFlight, build, submit, and release requests.
- Very specific: line 32
Commit the app.json build/version bump before archive or upload.
- Very specific: line 41
Treat every response as untrusted input.
- Very specific: line 66
Before squash-merging with --delete-branch, verify no open PR uses that branch as its base.
- Distinctive: line 83
Never close an issue that was not actually finished, and never leave finished work with the issue still open.
≈ “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
Threadbase Mobile — Codex Instructions
Keep this file to repository-specific behavior and safeguards. Agent tooling is documented in docs/agents/tooling.md; operational diagnosis belongs in docs/troubleshooting.md.
Verification
- Standard checks are
npm run lint,npm run typecheck,npm run test:ci, andnpm run test:scripts. - Before committing JavaScript or TypeScript, run
npx eslinton the staged JS/TS files. Errors block; warnings do not. i18next/no-literal-stringis an error. Put user-facing copy in translations. For technical literals, use a narrowly scoped disable with a reason; never exclude a mixed-copy file.- Keep finite translation choices statically visible: state, props, helpers, and option metadata carry semantic values, while the nearest presentation boundary maps them through literal
t('namespace:key')calls. Do not pass translation keys as application data or hide them withpreservePatternsor artificial usage manifests;npm run test:i18nusesi18next-cli statusandstatus --unusedto reject missing, incomplete, and stale keys.
E2E testing
- Maestro flows and fixtures live in
e2e/;npm run test:e2e:mockis the authoritative mock suite. Add new flows to the relevanttest:e2e:*script and prefertestIDover unstable visible text. The GitHubE2Eworkflow shards that same list across parallel jobs after one Release build per platform; do not duplicate the flow list in the workflow YAML. - On iOS 26.x, never use Maestro
hideKeyboard; scroll instead, or use Enter only for safe single-line inputs. XCTest/SpringBoard automation crashes are simulator failures, not app crashes. See docs/troubleshooting.md. - Shut down any iOS simulator or Android emulator you booted before the session ends (
xcrun simctl shutdown <UDID>and quit Simulator.app once nothing is booted;adb emu killfor Android). Never erase a device; leave one that was already booted as found, and only if you recorded it as booted at the start.
UI and components
- Never use emoji as UI icons. Use
phosphor-react-nativein all new or touched UI. - Every new
components/**/*.tsxfile requires a colocated*.stories.tsxin the same commit. Rare exemptions require a reason inscripts/git-hooks/story-exempt.txt. Add a story when modifying an existing component if the change is small. See docs/storybook.md.
Native dependencies and builds
- When
package.jsonorpackage-lock.jsonchanges, runpod installinios/and keeppackage.json,package-lock.json, andios/Podfile.locktogether. - Treat checksum-only drift for
ExpoModulesCore,ExpoWidgets,hermes-engine, andRNSentryas path noise; usescripts/reset-podfile-lock-path-noise.shrather than committing it. - Every physical iOS device build/install must use
scripts/dev-device.sh. Never callnpx expo run:ios --devicedirectly or introduce another device-build path. The script supplies the per-target App Groups signing profiles. Simulator builds are unaffected.
Shipping
- Use
/expo-local-shipfor ordinary ship, TestFlight, build, submit, and release requests. - Commit the
app.jsonbuild/version bump before archive or upload. - Version bumps land through
scripts/admin-merge-pr.sh, never by pushing directly tomain. Follow the branch and commit formats in docs/deployment.md. /ship-expo-cloudis opt-in only. Invoke it only when the user explicitly types that command, and obtain confirmation before any EAS build or submit command.- Before deploying to QA, Beta, or Production via the respective workflows, always ask which platform(s) to deploy to: iOS, Android, or both. Do not assume or default to
all; get explicit confirmation of the platform choice in every deployment request unless the user specified it in their message.
Server compatibility
The mobile client absorbs streamer evolution: a newer server may degrade a screen but must not crash the app.
- Treat every response as untrusted input. Narrow unknown statuses and fall back to
idle; do not rely on TypeScript exhaustiveness at the wire boundary. - Missing optional fields omit only the affected UI.
- Probe
GET /api/infoandGET /api/config/feature-flags; hide or explain unsupported features instead of throwing. A failed probe means the feature is off. - Report malformed data while keeping the rest of the screen alive. Do not invent client-side repair shims or pin a minimum server version.
Session ownership terms
- External: a session the streamer discovered but does not own (
ownership: 'external',isExternalSession). The app shows it read-only: it never sends input to it and never takes it over. - The user-facing word is "External", never "Observed". The session tier and its i18n key are
external; the read-only capability flag isisExternalOnlyand its locale key isexternalOnly. - Allowed actions on an External session: favorite, rename, and terminate. Terminate calls
POST /sessions/:id/terminate, asks for confirmation first, and is offered only while the process is alive. - Managed: a session the streamer spawned.
- View only: a provider without live control, so its sessions can't be typed into. Shown as the "View only" chip; code names the flag
externalOnly/isExternalOnly, shared with External sessions.
Encryption (E2EE)
A server whose record carries serverPublicKey is pinned: its traffic is sealed and must never silently fall back to plaintext. See docs/e2ee-client.md.
retryableinservices/e2ee/context.tsis true for exactlyE2EE_CTX_UNKNOWNandE2EE_TRANSIENT. Every other code is a hard refusal to surface, never to retry — and a 429 arriving after a hard refusal is the server reacting to our own retries, not new information.- A sealed socket that receives a non-binary frame throws. React Native delivers binary frames as
ArrayBuffer, notUint8Array; convert, never widen the accepted shape to strings. - A pairing that gets no message 2 is a failed pairing, not a plaintext success. This is what protects a user whose streamer sits behind an edge gate.
- Contexts are never rekeyed in place: a new key is a new context. Socket contexts die with the socket; the REST context rolls over on 24h / 1 GiB / every foreground with a 10 s drain.
Repository workflows
- PR titles use
type(scope)?: imperative summarywithfeat,fix,chore,docs,test,ci,perf, orrefactor; branches use the matchingtype/kebab-case-summary. Work explicitly targetingintegration-merge-354-355-376uses that branch as its base and rebases onto its latest tip. - Before squash-merging with
--delete-branch, verify no open PR uses that branch as its base; preserve a non-leaf branch until dependents are retargeted or merged. - GitHub issue and triage conventions are delegated to docs/agents/issue-tracker.md and docs/agents/triage-labels.md. Domain documentation uses one root
CONTEXT.mdplusdocs/adr/; see docs/agents/domain.md.
Headless Linux agents
Headless Linux cannot run native builds, CocoaPods, shipping scripts, Maestro, or device/simulator tooling. It can run the JS checks and Expo Web.
For browser smoke tests, start the bundled mock streamer from e2e/mock-server.js; because it has no CORS headers, front it with a development-only CORS proxy outside the repository. Expo Web is an early spike with expected native-only gaps; see docs/expo-web-support.md.
Issue status updates
Any change traceable to an existing issue ends with a status update on that issue — code, docs, tests, config, a revert, or a deletion all count. The issue is the record; a commit message, a PR body, or a chat reply is not a substitute.
- Completed — close the issue, with a comment naming what landed and where (PR or commit).
- Partly completed — leave it open and comment with what is done, what remains, and anything the remainder now depends on.
- Not done — leave it open and comment with why: blocked, superseded, out of scope, or a precondition that has to change first.
Never close an issue that was not actually finished, and never leave finished work with the issue still open. If one change resolves several issues, update each of them.
Product claims
Threadbase's one hosted service is the optional Threadbase relay, which carries end-to-end encrypted traffic and stays off in stable streamer releases. Otherwise the app talks only to streamers the user runs, and README.md and docs/FEATURES.md state that as fact. Before writing or changing anything about relays, hosted backends, self-hosting, or where data goes, read docs/no-hosted-service.md.
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.

