Contributing

How to work on teaspill itself — the repo layout, the build and test bar, the conventions, and where the design history lives.

You only need this section if you're working on teaspill itself. Everything here is about the source repository — its layout, how to build and test it, and how the pieces fit together. If you're building agents with teaspill, the Guides and Reference are where you want to be.

The repository

teaspill is a single pnpm workspace. Every published package lives under packages/ — the SDKs and CLI you use, the platform services you run, and the quality kits that keep the durability guarantees honest. The package map walks through all thirteen.

Alongside the packages, the repo root carries what runs and ships them: docker-compose.yml and docker-compose.overlay.yml (the self-hosted stack plus the reference deployment that the quick start and Self-hosting guide drive), .env.example, and scripts/ for backup and restore. This documentation site is itself a workspace package (@teaspill/docs).

Running the repo

You need Node 20.19 or newer and pnpm. Install once from the repo root:

pnpm install

Three checks make up the bar every change must clear:

pnpm -r typecheck
pnpm -r test
pnpm lint

pnpm -r fans out across the whole workspace. All three must be green before any work is committed. Changes to the documentation site add one more: pnpm --filter @teaspill/docs generate must prerender cleanly — a docs site that doesn't build is not done.

Most tests run entirely offline against in-process fakes and the real durability primitives, so the default run needs nothing else installed. Suites that need live infrastructure — a running gateway, Postgres, or the durable streams server — skip themselves when the service isn't there, which keeps the offline run green. You opt in by pointing a suite at a real service: set TEASPILL_STACK_URL (and an API key) for the end-to-end conformance suites, DATABASE_URL for the Postgres integration tests, TEASPILL_CHAOS=1 for real fault injection, and so on. Each package's README lists the exact variables it reads.

Conventions

Commits use conventional-commit subjects: feat:, fix:, chore:, docs:, test:.
Language. TypeScript throughout, ESM only, Node 20.19+.
Pinned versions. TypeScript is capped for compatibility with the lint toolchain, and several dependencies are exact-pinned — never with a caret — because they must match a protocol on the other side: the Restate SDK, the durable streams client (paired to the server image), and the Claude Agent SDK (paired to its goldens). Bump these deliberately, one at a time, and re-run the affected suite.

Where the design history lives

The docs teach how teaspill works today. They don't carry the why behind each decision — that history is deep, and it belongs to contributors.

teaspill's full design history — every architectural decision and why — lives in the repository under work/ (start with work/README.md).

The documentation site

This site lives in packages/docs, built on Nuxt Content. Every page is a Markdown file under content/, ordered by numeric filename prefixes. To work on it:

pnpm --filter @teaspill/docs dev

That serves the site locally with hot reload. To produce the static build that gets deployed:

pnpm --filter @teaspill/docs generate

Ready to see how the code is organized? The package map covers every package — what it's for, its public surface, and whether it's something you use or something you'd only touch as a contributor.

Configuration

Every environment variable, grouped by surface — the compose stack, the gateway, the CLI and clients, and the developer-deployed agent-loop and executor.

The package map

All thirteen teaspill packages — what each is for, its public surface, and whether you use it or only touch it as a contributor.