Rat Stack

An Effect stack so pure (aspirational) Kit Langton will blush.

The goal is to build the best Effect + Alchemy application we can. This is the reference for building an app and its cloud as one typed program. Effect owns the hard parts. Alchemy infers the infrastructure from the code. The fence raises the floor, so agents can build it and you can still trust it.

Vendor it like a library. Keep the bins you need and pull the rest.

Connect an agent

Paste this into your coding agent:

Read https://ratstack.sh/llms.txt and use rat-stack as the reference
for how we build: Effect for the hard parts, Alchemy for the
infrastructure, and a fence that makes the easy path the right
one. Search its rules and skills before you write code, follow
its patterns, and tell me when my code breaks them.

Or connect the MCP server directly:

# Claude Code
claude mcp add --transport http rat-stack https://ratstack.sh/mcp

# Codex
codex mcp add rat-stack --url https://ratstack.sh/mcp

Cursor reads ~/.cursor/mcp.json:

{ "mcpServers": { "rat-stack": { "url": "https://ratstack.sh/mcp" } } }

Install the skills into any agent that reads a skills folder:

npx skills add joelhooks/rat-stack

Supports MCP protocol versions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05. Clients on protocol 2026-07-28 are served without sessions; older clients get a session of their own, held by a Durable Object.

Four ideas

The vision has the sources and the reasoning.

The shelf

These packages have separate jobs. Follow the removal checklists before cutting a bin; a package name alone does not prove one-line removal.

  labeled · push in · pull out · self-contained · easy to trash

  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
  │ capability │ │ core       │ │ database   │ │ auth       │
  │ contracts  │ │ handlers   │ │ D1 · PG    │ │ Better Auth│
  └────────────┘ └────────────┘ └────────────┘ └────────────┘

  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
  │ devtools   │ │ web        │ │ infra      │ │ fence      │
  │ call logs  │ │ TanStack   │ │ Alchemy    │ │ types · CI │
  └────────────┘ └────────────┘ └────────────┘ └────────────┘
       in             in             in             in

  ┌────────────┐ ┌────────────┐ ┌─────────────────────┐
  │ events     │ │ lore       │ │ subscriber-delivery │
  │ analytics  │ │ graph      │ │ delivery adapter    │
  └────────────┘ └────────────┘ └─────────────────────┘

  ┌────────────┐
  │ front door │  coming: its own cartridge
  │ REST · MCP │
  │ A2A · code │
  └────────────┘
A shelf of current rat-stack bins: capability, core, database, auth, devtools, events, lore, subscriber-delivery, web, infra stack, and fence. The generic agent front door becoming its own cartridge is coming.

What to notice: these bins exist today. The hosted REST, MCP, A2A, and sandbox routes already run; extracting their generic front door into its own cartridge is coming.

Hexagonal architecture keeps job-shaped ports in core and provider adapters outside it. HATEOAS explains links that guide an agent's next action, including agent-only page guidance. Analytics is a running capture system; interest signup shows consent and confirmation across a delivery adapter.

One capability, every surface

              ┌─────────────────────────────────────┐
              │  one contract + capability          │
              │  Effect Schema: input · output · err│
              │  one Effect handler                 │
              │  XState when the work has states    │
              └──────────────────┬──────────────────┘
                                 │  defineContract → implement
    ┌────────────┬────────────┬────────────┬────────────┬────────────┐
    ▼            ▼            ▼            ▼            ▼
  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
  │ command  │ │   HTTP   │ │   MCP    │ │   RPC    │ │ sandbox  │
  │   line   │ │ + OpenAPI│ │  tools   │ │ browser  │ │ code mode│
  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘

  checked by  TypeScript 7 · Oxlint · Vitest · lefthook
  shipped by  pnpm · Turborepo · Alchemy → Cloudflare Worker
One capability projected to the command line, HTTP with OpenAPI, MCP tools, browser RPC, and sandbox code mode

What to notice: all five projections share one contract and handler. RPC serves the browser; it is not an agent interface.

The pattern in code

This is the whole search capability. Every surface below calls it.

export const search = implement(searchContract, ({ limit, query }) =>
  ContentStore.use((store) => store.search(query, limit)).pipe(
    Effect.map((matches) => ({ matches, total: matches.length }))
  )
);

What to notice: the schemas and handler share one contract, so the command line, HTTP, MCP, RPC, and sandbox projections cannot quietly disagree. RPC serves the browser.

Learn the stack

Skills are short guides your agent can install (see above). You can also just read them here.

Start here

See how the pieces fit

Learn by building

Choose what you keep

Keep the fence sharp

Ship with evidence

These pieces are pre-release (Effect 4 rc, XState 6 alpha, TypeScript 7, Alchemy beta). APIs move; pins.md has the exact versions this repo builds against.

Source files