# Rat Stack

> An open-source TypeScript scaffold and reference site for building Effect and Alchemy applications with agent-facing MCP, HTTP, and CLI interfaces.

Rat Stack is an MIT-licensed TypeScript template and reference site by Joel Hooks for building an application and its cloud infrastructure as one typed program. It combines Effect 4, XState 6, Alchemy, and a set of compiler, lint, and commit-hook checks the project calls the fence. The site publishes its rules, skills, and lore as Markdown for coding agents to read.

## What It Is

Rat Stack is a pnpm and Turborepo workspace template you copy into your own project and keep under your control. It includes a working Effect v4 CLI, tests, formatting, and type-aware linting, plus vendored source mirrors for Effect, effect-solutions, XState, and Alchemy. Its stated goal is the best Effect and Alchemy application the author can build. The README notes that the public tree is for borrowing ideas and carries no product support promise.

## One capability, several interfaces

You define a contract with Effect Schema input, output, and error types, then bind it to a server-side handler. That capability is projected onto the command line, HTTP with an OpenAPI document, MCP tools, browser RPC, and a sandboxed code mode. In the README example, the same inspectFile capability is the stats command, a POST /inspectFile endpoint, and an MCP tool over stdio. Code mode gives a model search and execute tools, running the program in a restricted Node subprocess.

## Connecting an agent

The site serves every page as Markdown by default, with an llms.txt agent guide. You can paste a prompt into a coding agent or add the hosted MCP server at ratstack.sh/mcp to Claude Code, Codex, or Cursor. Skills are loaded into a single session rather than installed into skill folders. A learn mode explains concepts while your agent works, storing progress locally in ~/.rat-learn/ and not sending your code, paths, names, or prompts.

## Packages and trimming

The repo ships packages for capability definitions, core services, database, auth via Better Auth, devtools, analytics events, lore content graph, signup delivery, deployment, and Alchemy infra. The README gives keep-or-cut checklists for removing features such as the CLI, HTTP, MCP, code mode, analytics, auth, or the deployment driver. XState 6 and Alchemy are described as pre-release, with exact versions listed in pins.md.

## Features
- Contracts with Effect Schema input, output and error definitions
- One capability projected to CLI, HTTP with OpenAPI, MCP tools, browser RPC, and sandboxed code mode
- Hosted MCP server and Markdown-first agent guide (llms.txt)
- Learn mode with local progress storage
- Session-scoped agent skills
- Fence of compiler checks, lint rules, and commit hooks
- Keep-or-cut removal checklists for packages
- Alchemy infrastructure declarations for Cloudflare
- Vendored source mirrors for Effect, XState, and Alchemy
- Typed feature flags and request analytics packages

## Integrations
Effect, Alchemy, Cloudflare, XState, MCP, Better Auth, Foldkit, Claude Code, Codex, Cursor, OpenAPI, Turborepo, pnpm

## Platforms
CLI, WEB, API

## Pricing
Open Source

## Links
- Website: https://ratstack.sh
- Documentation: https://ratstack.sh/learn
- Repository: https://github.com/joelhooks/rat-stack
- EveryDev.ai: https://www.everydev.ai/tools/rat-stack