A TypeScript monorepo designed for human <> agent collaboration.

Website  ·  Notes on agentic coding  ·  MIT

bunx degit mateoroldos/effect-forge my-app

About

Agents write code faster than anyone can review it. effect-forge is a monorepo template shaped around that problem — types and traces that make behaviour inspectable, boundaries that keep changes small, and checks fast enough that an agent proves its own work before you read a line of it.

It is opinionated: Effect, Bun, PostgreSQL, and Cloudflare, wired together and deployed by Alchemy.

AGENTS.md                conventions every agent reads
skills/effect-forge/     playbooks, loaded per task

apps/
├─ web                   TanStack Start application
├─ api                   Effect HTTP API
│  └─ src/infrastructure database and telemetry composition
└─ site                  the project's landing page

packages/
├─ domain                the domain model
├─ core                  application services and ports
├─ contracts             typed HTTP contracts
└─ ui                    shared visual vocabulary

adapters/
├─ auth-better           Better Auth inbound adapter
└─ database-postgres     PostgreSQL port implementations

alchemy.run.ts           infrastructure as code

Development

Bootstrap a checkout and authenticate the local Alchemy profile:

mise trust
mise run setup
bun alchemy login --configure

Maple is an OpenTelemetry-native platform for exploring traces, logs, and metrics. Effect Forge can send correlated browser and API telemetry to Maple, but keeps it disabled by default:

bun run dev

Enable telemetry with a local Maple instance:

bun run dev:telemetry

To connect a deployment to hosted Maple, provide its endpoint and separate server and browser ingest keys:

TELEMETRY_ENABLED=true
MAPLE_ENDPOINT=https://ingest.maple.dev
MAPLE_INGEST_KEY=...          # private server ingest key
MAPLE_BROWSER_INGEST_KEY=...  # publishable browser ingest key

mise derives STAGE from the user and checkout directory. Each clone, git worktree, or jj workspace therefore gets its own Neon branch and local Alchemy stage, branched from the staging project — so staging has to exist first.

Validation

bun run test    # tests only
bun run check   # formatting, lint, types, and tests
bun run build   # production builds

CI runs check and build.

Deployment

internal PR with preview label
  → CI
  → EffectForge:pr-<number>
  → preview URL posted on the PR

label removed or PR closed
  → preview destroyed

merge to main
  → CI
  → EffectForge:prod

Pull requests without the preview label run validation only. Forks cannot access deployment credentials. Deployments to the same stage are queued because Cloudflare.state() does not lock concurrent writes.

docs/deployment.md covers the stages and the one-time maintainer setup.