Development Guide

This guide covers how to set up a development environment and contribute to Sesame.

Prerequisites

Bun v1.0 or later

Getting Started

1. Clone the Repository

git clone https://github.com/jakejarvis/sesame.git
cd sesame

2. Install Dependencies

bun install

3. Set Up Environment

cp .env.example .env

# Generate secrets
echo "BETTER_AUTH_SECRET=$(openssl rand -base64 32)" >> .env
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

4. Start Development Server

bun run dev

This starts:

Frontend: http://localhost:13530 (Vite + TanStack Router)
Backend: http://localhost:13531 (Hono API)

Project Structure

Key Directories

Directory	Purpose
`apps/server/`	Hono backend API
`apps/web/`	TanStack Router frontend
`packages/shared/`	Shared types, Zod schemas
`packages/db/`	Database schema and migrations
`packages/sandbox/`	Sandbox provider implementations
`packages/agents/`	Agent executor implementations

Common Tasks

Running Tests

# Run all tests
bun run test

# Run tests for specific package
bun run test --filter=@sesame/shared

Type Checking

# Check all packages
bun run check-types

Linting

# Lint all code
bun run lint

# Fix auto-fixable issues
bun run lint --fix

Formatting

bun run format

Database Operations

# Generate migration from schema changes
bun run db:generate

# Run pending migrations
bun run db:migrate

# Push schema directly (dev only)
bun run db:push

# Open Drizzle Studio
bun run db:studio

Adding Features

Adding a New API Route

Create route file in apps/server/src/routes/:

apps/server/src/routes/my-feature.ts

import { Hono } from "hono";
import { authMiddleware } from "../middleware/auth";

const app = new Hono()
  .use(authMiddleware)
  .get("/", async (c) => {
    return c.json({ message: "Hello!" });
  })
  .post("/", async (c) => {
    const body = await c.req.json();
    // Handle request
    return c.json({ success: true });
  });

export default app;

import myFeatureRoutes from "./my-feature";

const api = new Hono()
  // ... existing routes
  .route("/my-feature", myFeatureRoutes);

Adding a New Page

Create route file in apps/web/src/routes/:

apps/web/src/routes/my-page.tsx

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/my-page")({
  component: MyPage,
});

function MyPage() {
  return (
    <div>
      <h1>My Page</h1>
    </div>
  );
}

TanStack Router automatically picks up new files in routes/.

Adding a New Agent

See Adding Agents for detailed instructions.

Adding a New Sandbox Provider

See Adding Sandboxes for detailed instructions.

Code Style

TypeScript

Use strict TypeScript (strict: true)
Prefer type over interface for object types
Use Zod for runtime validation

React

Use functional components with hooks
Prefer composition over prop drilling
Use TanStack Query for server state

Naming Conventions

Type	Convention	Example
Files	kebab-case	`my-component.tsx`
Components	PascalCase	`MyComponent`
Functions	camelCase	`myFunction`
Constants	SCREAMING_SNAKE	`MAX_RETRIES`
Types	PascalCase	`UserSettings`

Pull Request Guidelines

Create a branch from main:
```
git checkout -b feat/my-feature
```
Make changes following the code style

Test your changes:

bun run check-types
bun run lint
bun run test

Commit with conventional commits:

git commit -m "feat: add new feature"
git commit -m "fix: resolve issue with auth"
git commit -m "docs: update API documentation"

Push and create PR:
```
git push -u origin feat/my-feature
```

Debugging

Backend Logs

# View server logs
bun run dev --filter=@sesame/server

# Enable debug logging
DEBUG=* bun run dev --filter=@sesame/server

Frontend DevTools

React DevTools for component inspection
TanStack Query DevTools (enabled in dev mode)
Network tab for API requests

Database Inspection

# Open Drizzle Studio
bun run db:studio

Getting Help

GitHub Issues for bugs
GitHub Discussions for questions
Check existing issues before opening new ones

Development Guide

On this page