lobsterroll: Instructions file for Codex

AGENTS.md — For AI Coding Agents

This file helps AI coding agents (Claude Code, Codex, Cursor, Windsurf, Copilot, etc.) understand and work with this codebase effectively.

What This Is

Lobster Roll is an agent-native messaging platform — a Slack/Discord alternative where AI agents are first-class participants. Built as a pnpm monorepo with TypeScript.

Quick Setup (Non-Interactive)

# Clone and install
git clone https://github.com/onEnterFrame/lobsterroll.git
cd lobsterroll
pnpm install

# Start infrastructure (PostgreSQL + Redis)
docker compose up postgres redis -d

# Wait for services
sleep 5

# Copy env and set DATABASE_URL
cp .env.example .env
# DATABASE_URL=postgresql://lobsterroll:lobsterroll@localhost:5432/lobsterroll
# REDIS_URL=redis://localhost:6379

# Run all migrations in order
for f in packages/db/drizzle/*.sql; do psql $DATABASE_URL < "$f"; done

# Build (order matters!)
pnpm --filter @lobster-roll/shared build
pnpm --filter @lobster-roll/db build
pnpm --filter @lobster-roll/api build
pnpm --filter @lobster-roll/web build

# Verify
pnpm typecheck

Project Map

packages/shared/src/
  types/          # TypeScript interfaces (Account, Message, Channel, etc.)
  schemas/        # Zod validation schemas for API input
  constants/      # Error codes, defaults, limits
  utils/          # Mention parser, slug generator

packages/db/src/
  schema.ts       # ALL database tables (Drizzle ORM) — single file
  relations.ts    # Drizzle relational query definitions
  client.ts       # Database connection factory
  drizzle/        # Migration SQL files (applied in order: 0001, 0002, ...)

packages/api/src/
  app.ts          # Fastify app factory — ALL route registration happens here
  config.ts       # Environment variable validation (Zod)
  routes/         # HTTP route handlers (one file per resource)
  services/       # Business logic classes
  middleware/     # Auth, permissions, workspace context
  plugins/        # Fastify plugins (database, redis, websocket, cors, etc.)
  workers/        # BullMQ background workers (mention delivery, timeout)

packages/web/src/
  pages/          # Route-level React components
  components/     # Reusable UI components
  hooks/          # React hooks (WebSocket, presence, notifications)
  api/            # API client + React Query hooks
  utils/          # Slash commands, helpers
  types.ts        # Frontend types (duplicated from shared, not imported)
  main.tsx        # App entry + router