whatsapp-claude-agent: Instructions file for Codex

Project Documentation

MUST READ before working on this codebase:

• documentation/architecture.md — system overview, components, directory structure
• documentation/commands.md — WhatsApp slash commands reference
• documentation/configuration.md — config schema, CLI mapping, save/load
• documentation/message-flow.md — message pipeline, Claude queries, permissions

MUST UPDATE documentation when making changes. Keep it terse, accurate, no fluff.

Development Workflow

CRITICAL: Before making ANY code changes, start the TypeScript watch process in the background:

bun run tsc:watch &

This is MANDATORY. The watch process catches type errors immediately as you edit. Check the output after each edit to catch errors early. If you see TypeScript errors, fix them before moving on.

Optionally, also run tests in watch mode:

bun test --watch &

After editing code, always run the formatter and linter:

bun run format
bun run lint

Both commands are MANDATORY after code changes. Fix any lint errors before proceeding.

CLI and Config Parity

All CLI options MUST be configurable via the config file. After adding or modifying CLI options, always verify the corresponding config file property exists in src/types.ts (ConfigSchema) and is properly merged in src/cli/config.ts.

Bun Runtime

Default to using Bun instead of Node.js.

• Use bun <file> instead of node <file> or ts-node <file>
• Use bun test instead of jest or vitest
• Use bun build <file.html|file.ts|file.css> instead of webpack or esbuild
• Use bun install instead of npm install or yarn install or pnpm install
• Use bun run <script> instead of npm run <script> or yarn run <script> or pnpm run <script>
• Use bunx <package> <command> instead of npx <package> <command>
• Bun automatically loads .env, so don't use dotenv.

APIs

• Bun.serve() supports WebSockets, HTTPS, and routes. Don't use express.
• bun:sqlite for SQLite. Don't use better-sqlite3.
• Bun.redis for Redis. Don't use ioredis.
• Bun.sql for Postgres. Don't use pg or postgres.js.
• WebSocket is built-in. Don't use ws.
• Prefer Bun.file over node:fs's readFile/writeFile
• Bun.$ls instead of execa.