opencode/packages/app/AGENTS.md

Priorities

• Prioritise, in this order: stability, simplicity, performance.
• Before changing session or timeline code, record a production benchmark baseline and compare it after the change.

Debugging

• NEVER try to restart the app, or the server process, EVER.

Local Dev

• opencode dev web proxies https://app.opencode.ai, so local UI/CSS changes will not show there.
• For local UI changes, run the backend and app dev servers separately.
• Backend (from packages/opencode): bun run --conditions=browser ./src/index.ts serve --port 4096
• App (from packages/app): bun dev -- --port 4444
• Open http://localhost:4444 to verify UI changes (it targets the backend at http://localhost:4096).

SolidJS

• Always prefer createStore over multiple createSignal calls

Localization

• NEVER hardcode user-visible English strings in production code. ALWAYS use an i18n key for visible copy, placeholders, accessible labels, tooltips, menus, dialogs, toasts, empty states, and displayed errors.
• Feature work adds English source strings only. Leave non-English keys absent so the runtime English fallback applies; translations land separately after language review.
• Render count-sensitive copy only through language.plural(baseKey, count, params). Never select or pass .zero, .one, .two, .few, .many, or .other variants to language.t(...).
• When migrating existing copy to i18n, preserve the English text byte-for-byte unless the task explicitly requests a copy change.
• NEVER change existing English text or English keys to facilitate translation. English is intentional, designer-written source copy; adapt locale-specific translations and i18n mechanics around it.
• Keep locale complexity behind the shared typed i18n APIs. Feature and component code should use language.t(...) for ordinary copy and language.plural(baseKey, count, params) for count-sensitive copy. It must not inspect the locale, call Intl.PluralRules, construct or select plural-category keys such as .one or .other, or branch on locale-specific grammar.
• Prefer complete translated phrases. Do not concatenate grammatical fragments or make call sites assemble sentences. Keep placeholders to irreducible dynamic values such as names, paths, and counts.
• If a translation cannot be expressed by the current API, deepen the shared language/UI i18n module so one typed call owns locale selection, plural resolution, fallback, and interpolation. Do not leak that machinery into product code.
• Do not translate from model knowledge alone. Verify terminology and grammar with Unicode CLDR locale/plural data, Microsoft Localization Style Guides and terminology, Apple localization/style guidance and localized platform UI, Mozilla localization style guides, Mozilla Pontoon, and the Firefox localization corpus at github.com/mozilla-l10n/firefox-l10n.
• For developer-facing terminology, prefer the words already used by the target language's developer community over literal dictionary translations. Cross-check maintained localized developer products such as Firefox, KDE, and VS Code; use at least two independent corpora when they are available. If established practice keeps an English loanword or acronym, keep it rather than inventing a translation.
• Translate complete UI phrases in context. A glossary hit is evidence, not permission to translate word-by-word. Check terse labels such as session, prompt, agent, model, fork, shell, terminal, workspace, and worktree in the same grammatical role before choosing a term.
• Before a locale is ready, audit recurring concepts for one consistent translation and review every value that still equals English. Classify retained English as a product name, provider/tool name, URL, code token, keyboard legend, acronym, asset name, or established borrowing; translate unexplained leftovers.
• In translation review notes, name the corpora used and call out uncertain or region-specific terminology so native speakers can focus review where it matters.
• Also use the relevant language authority or official dictionary for the locale (for example RAE/Fundéu, FranceTerme, Duden, TDK, Kotus/Kielitoimiston sanakirja, Språkrådet/Bokmålsordboka, Rada Języka Polskiego/PWN, the Russian and Arabic language academies, the Ukrainian Orthography, Taiwan MOE dictionaries, or the Royal Society of Thailand). Treat the English dictionary as the semantic source of truth and preserve placeholders, code identifiers, product names, and keyboard labels.

Tool Calling

• ALWAYS USE PARALLEL TOOLS WHEN APPLICABLE.

Browser Automation

Use agent-browser for web automation. Run agent-browser --help for all commands.

Core workflow:

1. agent-browser open <url> - Navigate to page
2. agent-browser snapshot -i - Get interactive elements with refs (@e1, @e2)
3. agent-browser click @e1 / fill @e2 "text" - Interact using refs
4. Re-snapshot after page changes