AGENTS.md

Task Completion Requirements

Keep local verification focused on the files and packages changed. Run the smallest relevant test set; do not run the full workspace test suite as a routine completion step.
- Use vp test run <test-files> for focused built-in Vite+ tests. Use vp run test only when the affected package specifically requires its test script.
- Backend changes must include and run focused tests for the changed behavior.
- Run targeted formatting, lint, and type checks for the affected scope when available.
Do not run repo-wide vp check, vp run typecheck, vp run test, or equivalent full-suite commands locally unless the user explicitly requests them. CI is responsible for the full verification suite.
After frontend feature development or any user-visible frontend behavior change, the primary agent must use the test-t3-app skill once after integrating the work. Launch one isolated environment, authenticate through the printed pairing URL, and verify the affected flow in the controlled browser.
- Subagents must not independently launch dev servers or repeat integrated browser verification unless their delegated task explicitly requires it.
- Stop dev servers, watchers, and other long-running verification processes when the focused verification is complete.

apps/server: Node.js WebSocket server. Wraps Codex app-server (JSON-RPC over stdio), serves the React web app, and manages provider sessions.
apps/web: React/Vite UI. Owns session UX, conversation/event rendering, and client-side state. Connects to the server via WebSocket.
packages/contracts: Shared effect/Schema schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types. Keep this package schema-only — no runtime logic.
packages/shared: Shared runtime utilities consumed by both server and client applications. Uses explicit subpath exports (e.g. @t3tools/shared/git) — no barrel index.
packages/client-runtime: Shared runtime package for sharing client code across web and mobile.

Use these as implementation references when designing protocol handling, UX flows, and operational safeguards.

This project vendors external repositories under .repos/ as read-only reference material for coding agents.

Prefer examples and patterns from the vendored source code over generated guesses or web search results.
Do not edit files under .repos/ unless explicitly asked.
Do not import from .repos/; application code must continue importing from normal package dependencies.
Manage vendored subtrees with vpr sync:repos; use vpr sync:repos --repo <id> to sync one configured repository.
When updating a dependency with a configured vendored subtree, sync that subtree in the same change so .repos/ matches the installed dependency version.
When writing Effect code, read .repos/effect-smol/LLMS.md first and inspect .repos/effect-smol/ for examples of idiomatic usage, tests, module structure, and API design.
When writing relay infrastructure code with Alchemy, inspect .repos/alchemy-effect/ for examples of idiomatic usage, tests, module structure, and API design.