rat-stack 🐀

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

Build an Effect app and its cloud as one typed program. Joel’s goal is the best Effect + Alchemy application we can build; VISION.md explains why. AGENTS.md sets exact pins, checks, and hooks. The public tree lets you steal ideas. It carries no product support promise.

The pnpm + Turborepo workspace includes a working Effect v4 CLI, tests, formatting, and type-aware linting. Vendored source mirrors cover Effect, effect-solutions, XState, and Alchemy.

Define a Contract with Effect input, output, and failure schemas plus annotations. Bind a server-side handler, then project the capability onto every agent surface25. The same inspectFile capability is the stats command, POST /inspectFile with an OpenAPI document, and an MCP tool over stdio.

Create a repository

gh repo create <name> --template joelhooks/rat-stack

Clone the new repository, then install and verify it:

nvm use
pnpm install
pnpm vendor:agent-sources
pnpm turbo run check test build

Node 24.18.0 and pnpm 11.3.0 are required. The requirement is declared in .nvmrc, engines, devEngines, and packageManager.

Workspace layout

Try the example CLI

The included stats command counts bytes, Unicode characters, words, and lines in a file:

pnpm cli stats README.md
pnpm cli stats README.md --json

After pnpm build, you can run the built entrypoint directly:

node apps/cli/dist/cli.js stats README.md

The same capability on the other surfaces:

pnpm cli openapi                 # OpenAPI 3.1 document for the REST projection
pnpm cli serve --port 3000       # POST /inspectFile, GET /openapi.json, GET /docs
pnpm cli mcp                     # MCP server over stdio, one tool per capability
pnpm cli mcp --code-mode         # MCP server with two tools: search and execute
pnpm cli catalog --types         # the `tools` declarations a code-mode program sees

Code mode21 is the fourth projection. The model gets search for ranked matches with TypeScript signatures and execute for JavaScript with tools in scope34. The program runs in a fresh Node subprocess under --permission. It cannot touch the file system or spawn processes. To call the host, it uses tools.<name>(input). The host validates the input schema and runs the same handler used by every other surface. Node’s permission model allows network egress. Put a Worker or Deno runtime behind the same Sandbox service to isolate the network too.

packages/capability/src is where a capability becomes a Command, an HttpApiEndpoint, a Tool, and a catalog entry. packages/core/src/inspect-file.ts supplies the CLI’s example capability. Hosted content has its own registry in apps/site/src/capabilities/index.ts. Provider adapters stay outside core (rat-stack-boundaries/no-core-adapters); apps provide them to core’s job-shaped ports at composition. Add another to capabilities27, then verify every projection you keep; CLI command registration lives in apps/cli/src/command.ts.

What is in the stack?

Every dependency is pinned exactly. Review pin upgrades as stack changes.

Commands

Agentic surface

Every clone includes AGENTS.md for repo law and commands, CLAUDE.md as Claude Code’s pointer to that law, and VISION.md for project intent. Source mirrors live under .agent_sources/ after you run the vendor script. Repo-local Pi extensions belong in .pi/extensions/.

Make it yours

Start with the template:

gh repo create <name> --template joelhooks/rat-stack

Clone the new repository, then install it:

pnpm install
pnpm sources:fetch

pnpm sources:fetch imports missing pinned source10 commits from the configured repository remotes once, including in template children. Generation reads only local Git objects and never fetches. Re-run the command when adding a new pin that is not present locally.

Rename the workspace package names before you build on the example. The current name fields are:

Rename the bin entry in apps/cli/package.json, the root command in apps/cli/src/command.ts, and the version in apps/cli/src/version.ts. Then change every matching import. The current workspace imports are @rat-stack/capability, @rat-stack/cli, @rat-stack/core, @rat-stack/infra, and @rat-stack/site. Find them with:

rg -n '@rat-stack/' --glob '*.json' --glob '*.ts' -l

A new scope changes line lengths, so run the formatter once after the rename:

pnpm fix

Replace inspectFile in packages/core with one useful capability. Add it to capabilities27, then verify each surface you keep. Rewrite the Project law, Architecture, and Boundaries sections of AGENTS.md and the top of .pi/APPEND_SYSTEM.md; they describe rat-stack until you do. Keep expected failures typed and map them to deliberate exit codes.

apps/site is the public site and Worker. apps/infra is its Alchemy Stack. Delete both if you do not want a public site. If you keep them, change the Cloudflare Zone name and the DNS names and targets derived from it in apps/infra/alchemy.run.ts. Change the Worker domain and redirects in apps/site/src/worker.ts. Choose an Alchemy stage for each plan or deploy. The stage is a command-line choice, for example --stage <stage>. Configure credentials with:

pnpm alchemy profile edit --add Cloudflare

Run the acceptance gate before the first push:

pnpm turbo run check test build

What it promises and how to check

Keep or cut

The template is a working project. Delete what you will not use on day one; the fence will identify dependent code that must go too. After each cut, trim packages/capability/src/index.ts and run pnpm install, pnpm fix, then pnpm turbo run check test build. Update the package list in AGENTS.md.

defineContract, implement, and toCommand are the minimum that keep stats working. The contract module has no dependency on the other projections.

License

MIT

Last changed 2026-10-29 in d82837c. Source on GitHub. Change log.

Linked from

  1. Agent rules for rat-stack (AGENTS.md). What you may change, which commands to run, and which changes need approval.
  2. Effect + Alchemy peer patterns. Source-grounded patterns from repos on nearby Effect and Alchemy pins.
  3. gardener. Keep rat-stack current and clean. Update exact dependency versions, learn from repos on the same versions, and add lint rules before cleanup.
  4. Learn mode presents concepts at useful depths. An agent presents source-derived concepts during real work and keeps learning events in a private local log.