# 🐀 Rat Stack

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:

```text
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:

```sh
# 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`:

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

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

```sh
npx skills add joelhooks/rat-stack
```

Every MCP client works. Clients on protocol 2026-07-28 are served without sessions; older clients get a session of their own, held by a Durable Object.

- [MCP connection details](https://ratstack.sh/.well-known/mcp.json)
- [HTTP API docs](https://ratstack.sh/openapi.json)
- [Short agent guide](https://ratstack.sh/llms.txt)
- [All public agent docs](https://ratstack.sh/llms-full.txt)

## Four ideas

- **Pieces.** An Alchemy Layer carries its own infrastructure. A service tag is the product's API. A Layer is one vendor's implementation. Swapping vendors is a one-line change.
- **Trust.** Make the easy path the right path. The codebase and the compiler stop mistakes that rules and style guides can only ask about. Remove a binding and the code that uses it stops compiling.
- **Floor.** Raise the worst case. Small cuts to failure rates multiply how long an agent can run unattended.
- **Range.** Think wider. Building got fast and deploying did not. Layers that carry their own infrastructure close that gap. If it compiles, it deploys.

The [vision](https://ratstack.sh/VISION.md) has the sources and the reasoning.

## The shelf

Every piece is a bin you can push in or pull out.

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

  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  │ capability  │ │ projections │ │ fence       │ │ stack       │
  │ one schema  │ │ CLI · HTTP  │ │ types · lint│ │ Alchemy →   │
  │ one handler │ │ MCP · code  │ │ hooks · CI  │ │ Cloudflare  │
  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
         in              in              in              in

  ┌─────────────┐ ┌─────────────┐
  │ database    │ │ front door  │
  │ D1 or       │ │ REST · MCP  │
  │ PlanetScale │ │ A2A, sandbox│
  └─────────────┘ └─────────────┘
        next           coming
```
Diagram: A shelf of labeled bins. In today: capability, projections, fence, and stack. Next: a database bin with D1 or PlanetScale. Coming: the agent front door.

What to notice: removing a bin means deleting its package and the one line that provides it. Everything else still passes the checks.

## One capability, every surface

```text
              ┌─────────────────────────────────────┐
              │  one capability                     │
              │  Effect Schema: input · output · err│
              │  one Effect handler                 │
              │  XState when the work has states    │
              └──────────────────┬──────────────────┘
                                 │  defineCapability
        ┌───────────────┬────────┴──────┬───────────────┐
        ▼               ▼               ▼               ▼
  ┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐
  │  command  │   │   HTTP    │   │    MCP    │   │  sandbox  │
  │   line    │   │ + OpenAPI │   │   tools   │   │ code mode │
  └───────────┘   └───────────┘   └───────────┘   └───────────┘

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

What to notice: the four boxes share one handler and one set of schemas. Add a capability once and every surface picks it up.

## The pattern in code

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

```ts
export const search = defineCapability("search", {
  annotations: {
    idempotent: true,
    readOnly: true,
  },
  description:
    "Search rat-stack repository law and skills. Returns stable resource ids for read.",
  failure: Schema.Never,
  handler: ({ limit, query }) => {
    const matches = searchContent(query, limit);
    return Effect.succeed({
      matches,
      total: matches.length,
    });
  },
  input: Schema.Struct({
    limit: Schema.optional(Schema.Finite),
    query: Schema.String,
  }),
  output: SearchOutput,
});
```

What to notice: the schemas and handler live together, so the command line, HTTP, MCP, and sandbox projections cannot quietly disagree.

## Learn the stack

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

### See how the pieces fit

- [learn-alchemy](/skills/learn-alchemy) — Learn how Alchemy 2 turns an Effect program into a planned Cloudflare deployment.
- [learn-rat-stack](/skills/learn-rat-stack) — See how Effect, XState, TypeScript, Alchemy, and four agent interfaces fit together.

### Learn by building

- [add-a-capability](/skills/add-a-capability) — Learn how one Effect action becomes a command, HTTP route, MCP tool, and sandbox call.
- [add-a-lifecycle-machine](/skills/add-a-lifecycle-machine) — Learn how XState owns a lifecycle while Effect owns its work, errors, and services.

### Choose what you keep

- [keep-or-cut](/skills/keep-or-cut) — Learn which pieces depend on each other, then keep only the ones your project needs.

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

- [AGENTS.md](/AGENTS.md) — What you may change, which commands to run, and which changes need approval.
- [VISION.md](/VISION.md) — What this starter is for and what a useful copy should keep.
- [README.md](/README.md) — What is in the repo, how the example works, and how to run it.
- [vendor/README.md](/vendor/README.md) — How to pin an unpublished package and when to remove the local copy.
- [pins.md](/pins.md) — Exact dependency values declared by every workspace package.
- [log.md](/log.md) — What changed in the files served here, newest first.
- [Effect 4 examples](/resources/effect-4-reference-projects.svx) — Working examples for the exact Effect version used by this repo.
- [One action, four interfaces](/resources/schema-projections-and-code-mode.svx) — Why one typed action powers the command line, HTTP, MCP, and sandbox.