Effect Agent Template

A batteries-included, opinionated TypeScript template for CRUD applications that also run long-lived AI agents. The example domain—projects, tasks, conversations, and agent sessions—is deliberately generic. Replace it while keeping the interfaces, dependency direction, durable command model, and security boundaries.

The monorepo uses pnpm 10 for workspace and dependency management, Turborepo 2 for package task orchestration and caching, Oxlint for fast code linting, and TypeScript 7 for repository-wide type safety. These versions are pinned in the root manifest and lockfile.

Run it

Requirements: Docker Desktop. For host development, also install Node 26 and pnpm 10.23.

docker compose up --build

Open http://localhost:5173, create an account, add a project, and run a prompt. Local mode uses a deterministic runtime, so it needs no AI or sandbox credentials. Postgres is exposed at localhost:5433; the API is at localhost:3000; the write-only credential broker is at localhost:3001.

To work on source with only Postgres in Docker:

docker compose up -d postgres
cp .env.example .env
pnpm install
pnpm db:migrate
pnpm dev

pnpm dev loads the optional root .env and starts persistent application tasks through Turborepo. pnpm build schedules deployable build tasks through Turbo; today that means the web production bundle. Workspace packages export TypeScript source and are validated together by pnpm typecheck rather than pretending to emit independent artifacts.

The CLI uses the same API through Device Authorization. On macOS it stores the bearer token in Keychain; other platforms use an owner-only 0600 file under the user config directory.

pnpm --filter @repo/cli exec tsx src/main.ts login
pnpm --filter @repo/cli exec tsx src/main.ts projects list

Validate locally before pushing:

pnpm guardrails
pnpm build
pnpm infra:check

pnpm guardrails runs lint, typecheck, architecture, dependency, template, and design checks plus the Docker-free test suite. The web production build also enforces a 750 KiB initial-entry budget; rich transcript rendering loads on demand. CI runs the same chain plus Postgres-backed integration tests, image builds, a Compose smoke test, and Helm lint. Postgres suites run locally too when DATABASE_URL points at a running database.

What is included

• Effect 4 services, Layers, Schema contracts, typed failures, recipes, and a pinned source-reference workflow.
• Better Auth with browser cookies and OAuth Device Authorization for the CLI, behind repository-owned interfaces.
• A React workbench using TanStack Query for server state and XState for client workflow state.
• shadcn source components, AI Elements source components, and Base UI isolated behind packages/ui.
• Durable Postgres admission, event history, approvals, cancellation, leases, retries, and worker processes.
• A provider-neutral AgentRuntime, a direct Effect/OpenAI Responses example, and pinned OpenCode SDK/CLI adapters.
• One OpenSandbox workspace per agent session, default-deny egress, and credential-vault bindings.
• A narrow, write-only secret upload broker with memory and AWS Secrets Manager implementations.
• Correlated HTTP responses and bounded, redacted provider diagnostics through @repo/observability.
• Non-root Docker images, complete Docker Compose development, Helm deployment, and an optional EKS Terraform baseline.
• Agent instructions, architecture/dependency checks, DESIGN.md token enforcement, an initial-bundle budget, Effect recipes, and template/domain-leak checks.

Repository map

apps/
  server/             public application and Better Auth API
  web/                browser client and design system
  cli/                device-authenticated terminal client
  worker/             durable jobs and runtime ownership
  credential-broker/  write-only secret ingress
packages/
  contracts/          Effect Schema protocol and domain values
  core/               readable application service interfaces
  db/ queue/           Postgres adapters and leases
  client/ client-react shared transport and Query integration
  agent-runtime/       provider-neutral agent port and deterministic fake
  agent-runtime-opencode/ OpenCode adapter
  sandbox/ sandbox-opensandbox/ isolation ports and adapter
  secrets/ ai/ auth/ ui/ config/ observability/
examples/effect-recipes/ focused idiomatic Effect examples
deploy/               Helm and optional EKS Terraform

Start with architecture, security, and adoption. The canonical implementation idioms are in patterns and the reasoning behind them in decisions. Deployment details are in deployment; live agent setup is in OpenCode and OpenSandbox.

Template philosophy

Public interfaces should read like the application. Adapters should contain vendor and protocol detail. Decode data at every boundary. Use transactions for a state change and its durable work record. Never hand credentials or runtime connection material to a client. Keep deterministic implementations strong enough to test complete behavior without network access.

See AGENTS.md before changing code and apps/web/DESIGN.md before changing the interface.