Repository Guidelines

Project Structure & Module Organization

• backend/: Express + TypeScript API that wraps the Codex CLI; entry point backend/src/index.ts; compiled output in backend/dist/.
• frontend/: React + Vite client with main bootstrap in frontend/src/main.tsx and UI logic in frontend/src/App.tsx; static assets live under frontend/public/, and production bundles land in frontend/dist/.
• Keep environment-specific configuration outside the repo (.env or shell exports) and document any new env vars in PRs.

Build, Test, and Development Commands

• cd backend && npm install: install backend deps; npm run dev: run tsx watcher on http://localhost:4000; npm run build: type-check and emit dist/; npm start: serve the built bundle.
• cd frontend && npm install: install UI deps; npm run dev: start Vite dev server with proxy to backend; npm run build: run tsc then bundle; VITE_API_BASE_URL=http://localhost:4000/api npm run preview: preview production bundle.
• Export Codex credentials (AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_KEY, AZURE_OPENAI_DEPLOYMENT) before launching the backend; override CODEX_WORKDIR when pointing Codex to another directory.

Coding Style & Naming Conventions

• TypeScript strict mode is enabled; prefer explicit types at module boundaries and validate request payloads via zod as in backend/src/index.ts.
• Use 2-space indentation, camelCase for variables/functions, PascalCase for React components, and descriptive file names (ThreadList.tsx, useCodexClient.ts if added).
• Run npm run build in both packages prior to PRs; match existing formatting until Prettier/ESLint configs are introduced.

Testing Guidelines

• Automated tests are not yet configured; add future backend tests alongside code (backend/src/__tests__/api.spec.ts) and frontend tests under frontend/src/__tests__/.
• Fallback validation: hit POST /api/run with curl or REST clients, and walk through the UI flow to confirm prompt/response loops; capture manual steps in PR descriptions.

Commit & Pull Request Guidelines

• Follow Conventional Commits, scoping messages where helpful (e.g., feat(frontend): persist thread history).
• Each PR should explain motivation, list manual or automated test results, call out environment variable changes, and include UI screenshots/log snippets when behavior shifts.
• Keep changes focused; update docs or configuration examples that drift alongside code updates.

Security & Configuration Tips

• Never commit secrets; rely on .env.local or shell exports and document required variables.
• Limit backend access by using the minimal CODEX_WORKDIR; ensure dependencies are reviewed for security before upgrades.
• Remove temporary logging or debugging code before merging to avoid leaking prompt data.