cview AGENTS.md

AGENTS.md

Repository instructions for coding agents. README.md is the human-facing product and contributor guide; keep agent-specific guidance here.

Bootstrap and verification

Use the Node version in .node-version. In a fresh checkout, install the locked dependencies and Chromium once:

npm run bootstrap

Use the smallest relevant test while iterating, then run the appropriate gate:

npm test -- path/to/file.test.ts  # focused Vitest run
npm run check                     # types, lint, design lint, Vitest, build
npm run check:all                 # check plus production Playwright flows

Run npm run check before handing off any source or configuration change. Run npm run check:all when a change can cross the server/browser boundary or affect navigation, themes, rendering, export, capture, or build configuration. For DESIGN.md-only work, npm run lint:design is the focused gate.

Where behavior belongs

• src/server.ts composes the app; filesystem, search, security, and HTTP/SSE behavior belongs in focused modules under src/server/.
• src/shared/contracts.ts parses and normalizes JSONL records and API responses.
• Frontend transport belongs in api/, pure conversation behavior in domain/, browser lifecycles in hooks/, and screen/display work in pages/ and components/.
• Live and standalone export behavior belongs in src/frontend/src/export/.
• For UI or export presentation changes, read DESIGN.md. Semantic colors live in styles/theme.css, shared conversation rules in styles/conversation.css, and typed React references in styles/tokens.ts.

Contracts to preserve

• Parse Claude records through the shared contracts and keep unknown record kinds visible instead of silently discarding them.
• Keep ~/.claude read-only and write derived indexes to the external cache. Never copy real session files into tests; use small JSONL files with invented data.
• Bind to loopback, reject non-local API clients/origins, and validate every project, session, and agent path segment before filesystem access.
• Keep cold filesystem scans bounded; do not fan out unbounded reads across all sessions.
• Preserve public CLI names, environment variables, API behavior, stored-data compatibility, message ordering, and stable message IDs unless requested.
• Standalone HTML must remain offline-capable. Re-export must not nest controls or create multiple toolbars, and capture must work in both themes.
• Keep heavy export/capture dependencies behind the existing lazy boundary.