Offworld Docs

Essential commands and workflows for developing Offworld.

Development Commands

Start All

bun run dev

Starts both frontend and backend with hot-reloading.

Start Frontend Only

bun run dev:web

Start Backend Only

bun run dev:server

Quality Checks

IMPORTANT: Run before committing:

# Lint and format (auto-fixes)
bun run check

# Type check all workspaces
bun run typecheck

Build

# Build all apps/packages
bun run build

# Build specific workspace
bun run build --filter web

File Watching

All dev commands have hot-reloading:

Frontend (TanStack Start):

Edit apps/web/src/**/*.tsx → instant refresh
Route changes auto-regenerate route tree

Backend (Convex):

Edit packages/backend/convex/**/*.ts → auto-push to Convex
Schema changes require restart

Testing Workflow

Manual Testing

Start analysis on small repo (<50 files)
Watch Convex Dashboard → Workflows tab
Verify progressive updates on frontend
Test chat with sample questions
Check auth flow (sign in/out)

Test Repositories

Good test repos:

oscabriel/offworld - Self-reference
shadcn-ui/ui - Medium complexity
tanstack/router - Well-structured

Avoid:

Very large repos (>5k files) - may timeout
Repos with unusual structures

Debugging

Frontend:

# Browser DevTools → Console
# Check React Query devtools
# Network tab for Convex calls

Backend:

# Convex Dashboard → Logs
# Filter by function name
# Check workflow execution steps

Common Development Tasks

Adding a New Route

Create apps/web/src/routes/your-route/index.tsx
Route tree regenerates automatically
Add to navigation in layout if needed

Adding a New Convex Function

Create/edit packages/backend/convex/[feature].ts
Export with query(), mutation(), or action()
Import in frontend: import { api } from "@offworld/backend"
Use: useQuery(api.feature.yourFunction, args)

Adding an Agent Tool

Define in packages/backend/convex/agent/tools.ts:

export const yourTool = createTool({
  name: "yourTool",
  description: "What this tool does",
  parameters: z.object({ ... }),
  execute: async (args, ctx) => {
    // Tool logic
  }
});

Add to agent in agent/codebaseAgent.ts

Modifying Schema

Edit packages/backend/convex/schema.ts
Run bun run dev:setup to apply
Clear data if breaking change: Convex Dashboard → Data → Delete table

Git Workflow

Branching

git checkout -b feature/your-feature

Committing

# Stage changes
git add .

# Check before commit
bun run check
bun run typecheck

# Commit (Biome runs on pre-commit hook)
git commit -m "feat: your feature description"