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

esbuild

Use

bun install

instead of

npm install

yarn install

pnpm install

Use

bun run <script>

instead of

npm run <script>

yarn run <script>

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.

Testing

Use

bun test

to run tests.

import { test, expect } from "bun:test";

test("hello world", () => {
  expect(1).toBe(1);
});

Frontend

Use HTML imports with

Bun.serve()

. Don't use

vite

. HTML imports fully support React, CSS, Tailwind.

Server:

import index from "./index.html"

Bun.serve({
  routes: {
    "/": index,
    "/api/users/:id": {
      GET: (req) => {
        return new Response(JSON.stringify({ id: req.params.id }));
      },
    },
  },
  // optional websocket support
  websocket: {
    open: (ws) => {
      ws.send("Hello, world!");
    },
    message: (ws, message) => {
      ws.send(message);
    },
    close: (ws) => {
      // handle close
    }
  },
  development: {
    hmr: true,
    console: true,
  }
})

HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically.

<link>

tags can point to stylesheets and Bun's CSS bundler will bundle.

<html>
  <body>
    <h1>Hello, world!</h1>
    <script type="module" src="./frontend.tsx"></script>
  </body>
</html>

With the following

frontend.tsx

import React from "react";
import { createRoot } from "react-dom/client";

// import .css files directly and it works
import './index.css';

const root = createRoot(document.body);

export default function Frontend() {
  return <h1>Hello, world!</h1>;
}

root.render(<Frontend />);

Then, run index.ts

bun --hot ./index.ts

For more information, read the Bun API docs in

node_modules/bun-types/docs/**.mdx