TURBOREPO MONOREPO AGENTS.MD

A TypeScript monorepo managed with pnpm workspaces and Turborepo. Monorepos are where a single root instruction file runs out of room, so this template also explains how to use nested AGENTS.md files per app.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
The Turborepo monorepo filesCustomize in the generator
AGENTS.mdFor Codex, Cursor, Copilot, Jules, Windsurf and more
# AGENTS.md

Project: acme-monorepo. A pnpm workspace monorepo orchestrated with Turborepo: web and API apps plus shared packages.

This file is the single source of truth for every coding agent working in this repository. The tool-specific files (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md and .cursor/rules/project.mdc) point here. Edit this file, not those.

## Stack

- Language: TypeScript
- Database: PostgreSQL
- Hosting: Vercel
- Tests: Vitest
- Package manager: pnpm

## Commands

Run these from the repository root.

- Install dependencies: `pnpm install`
- Run locally: `pnpm turbo run dev`
- Build: `pnpm turbo run build`
- Run all tests: `pnpm turbo run test`
- Run one test file: `pnpm turbo run test --filter=<package>`
- Lint: `pnpm turbo run lint`
- Type-check: `pnpm turbo run typecheck`
- Format: `pnpm prettier --write .`

## Project layout

- `apps/web/`: The web app (has its own AGENTS.md)
- `apps/api/`: The API service (has its own AGENTS.md)
- `packages/ui/`: Shared React components
- `packages/config/`: Shared ESLint and TypeScript configs
- `turbo.json`: Task pipeline and caching
- `pnpm-workspace.yaml`: Workspace package globs

## Code style

- Indent with 2 spaces. Never tabs.
- TypeScript runs in strict mode. Do not use `any`; use `unknown` and narrow it, or write the real type.
- Match the style and patterns of the surrounding code, even where you would personally choose differently.
- Use named exports. Do not add default exports.
- Never swallow an error. Handle it where you can act on it, or rethrow it with context about what failed.
- Commit messages follow Conventional Commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, with an imperative summary under 72 characters.
- Keep each change small and focused on one concern. Split unrelated fixes into separate commits.

## Working rules

- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Never write secrets, API keys, tokens or passwords into code, tests, fixtures, logs or commits. Read them from environment variables, and never commit `.env` files.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.
- Do not hand-edit generated files or lockfiles; change the source and regenerate.
- Change only what the task needs. Do not refactor, rename or reformat unrelated code.
- When you change commands, structure or conventions, update this file and the README in the same change.

## Project-specific notes

- Run tasks through Turborepo with `--filter=<package>` to limit work to what you changed, for example `pnpm turbo run test --filter=web`.
- Add a dependency to the package that uses it: `pnpm add <dep> --filter <package>`. Never add app dependencies to the root `package.json`.
- Internal packages are referenced with the `workspace:*` protocol.
- Shared code goes in `packages/`; apps never import from another app.
- Before changing a shared package, check its dependents with `pnpm turbo run build --filter=...<package>` and keep them building.
- The nearest AGENTS.md wins: when working inside `apps/web/`, follow `apps/web/AGENTS.md` in addition to this file.
- When adding a new task to a package, also declare it in `turbo.json` with correct `dependsOn` and `outputs`.

## Project phase

This project is in active development. Follow the patterns that already exist; consistency beats novelty.
CLAUDE.mdFor Claude Code
# CLAUDE.md

@AGENTS.md

## Claude Code

- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file, so every agent stays in sync.
- Put Claude-only preferences below this line. Personal, uncommitted notes belong in CLAUDE.local.md.
GEMINI.mdFor Gemini CLI
# GEMINI.md

@./AGENTS.md

## Gemini CLI

- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file.
- Alternative: delete this file and set "context": { "fileName": ["AGENTS.md"] } in .gemini/settings.json so Gemini CLI reads AGENTS.md directly.
.github/copilot-instructions.mdFor GitHub Copilot
# Copilot instructions

Project: acme-monorepo. A pnpm workspace monorepo orchestrated with Turborepo: web and API apps plus shared packages.

The full instructions are in AGENTS.md at the repository root. Read it before you change code; if anything here disagrees with it, AGENTS.md wins. The essentials are repeated below for Copilot surfaces that only read this file.

## Stack

- Language: TypeScript
- Database: PostgreSQL
- Hosting: Vercel
- Tests: Vitest
- Package manager: pnpm

## Commands

- Install dependencies: `pnpm install`
- Run locally: `pnpm turbo run dev`
- Build: `pnpm turbo run build`
- Run all tests: `pnpm turbo run test`
- Run one test file: `pnpm turbo run test --filter=<package>`
- Lint: `pnpm turbo run lint`
- Type-check: `pnpm turbo run typecheck`
- Format: `pnpm prettier --write .`

## Working rules

- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Never write secrets, API keys, tokens or passwords into code, tests, fixtures, logs or commits. Read them from environment variables, and never commit `.env` files.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.
- Do not hand-edit generated files or lockfiles; change the source and regenerate.
- Change only what the task needs. Do not refactor, rename or reformat unrelated code.
- When you change commands, structure or conventions, update this file and the README in the same change.
.cursor/rules/project.mdcFor Cursor
---
description: Project instructions for every task (mirrors AGENTS.md)
globs:
alwaysApply: true
---

# Project rules

The project instructions live in @AGENTS.md at the repository root, which Cursor loads automatically. They are not repeated here, so they cost context only once. Edit AGENTS.md, not this rule.

Before you change code, check the Commands and Working rules sections of AGENTS.md, and run its test and lint commands before you say a task is done.

Put Cursor-only rules below, or add scoped rules as more .mdc files with `globs` (for example `src/components/**/*.tsx`).

These are the exact files the generator writes for this preset. Change any command or rule in the generator and download your own set.

About the Turborepo monorepo preset

What Is in the Turborepo monorepo AGENTS.md?

The preset describes a a pnpm workspace monorepo orchestrated with Turborepo: web and API apps plus shared packages. Its AGENTS.md is 51 non-empty lines with 8 exact commands, 6 key directories, and 7 stack-specific rules on top of the shared working rules.

  • Commands: pnpm install, pnpm turbo run dev, pnpm turbo run build, pnpm turbo run test, pnpm turbo run test --filter=<package>, pnpm turbo run lint, pnpm turbo run typecheck, pnpm prettier --write ..
  • Layout: apps/web/, apps/api/, packages/ui/, packages/config/, turbo.json, pnpm-workspace.yaml.
  • Wrappers: CLAUDE.md and GEMINI.md import AGENTS.md; the Copilot file repeats the essentials; the Cursor rule points to AGENTS.md.

Why These Rules for Turborepo monorepo?

Root dependencies leak everywhere

Agents add packages at the root because it is the first package.json they see. That hides real dependencies and lets apps import things they never declared, which breaks when the app is deployed alone.

Filters keep the loop fast

Running every test in every package after a one-line change wastes minutes per iteration. Turborepo filters and caching make verification cheap enough that agents will actually do it.

Shared packages have blast radius

A change in packages/ui can break three apps. The dependents filter (...<package>) builds everything downstream so the agent sees the breakage before you do.

Nested AGENTS.md files

Codex, Cursor and other agents read the AGENTS.md nearest to the file being edited. Keeping app-specific rules in each app keeps the root file short and relevant.

Which Stack Rules Does the File Add?

  • Run tasks through Turborepo with --filter=<package> to limit work to what you changed, for example pnpm turbo run test --filter=web.
  • Add a dependency to the package that uses it: pnpm add <dep> --filter <package>. Never add app dependencies to the root package.json.
  • Internal packages are referenced with the workspace:* protocol.
  • Shared code goes in packages/; apps never import from another app.
  • Before changing a shared package, check its dependents with pnpm turbo run build --filter=...<package> and keep them building.
  • The nearest AGENTS.md wins: when working inside apps/web/, follow apps/web/AGENTS.md in addition to this file.
  • When adding a new task to a package, also declare it in turbo.json with correct dependsOn and outputs.

How Do You Add These Files to a Turborepo monorepo Repository?

  1. Download the zip above. It is laid out exactly as the files go into the repository.
  2. Unzip it at the repository root. AGENTS.md, CLAUDE.md and GEMINI.md go next to your README; the Copilot file goes in .github/ and the Cursor rule in .cursor/rules/.
  3. Open AGENTS.md and check every command against your package scripts or Makefile.
  4. Delete wrappers for tools your team does not use, and any old .cursorrules or .windsurfrules file.
  5. Commit, then run the linter on AGENTS.md whenever you change it.

Want different commands or rules? Load this preset into the generator, change anything, and download your own set.

Which Agents Will Read These Files?

AGENTS.md is read directly by Codex, Cursor, Windsurf, Cline, Zed and Jules, and by GitHub Copilot's cloud agent, code review and CLI. Claude Code reads it through the generated CLAUDE.md, and Gemini CLI through GEMINI.md. See the compatibility table for details, last verified 2026-11-13.

Which Similar Stacks Are in the Library?

All presets are on the stacks page.

Frequently Asked Questions

Should a monorepo have one AGENTS.md or many?

Both: a root file for repository-wide commands and rules, and a short AGENTS.md inside each app or package with what is specific to it. Agents that support nesting combine them, with the nearest file taking precedence.

Does this work with Nx instead of Turborepo?

The workspace rules do. Swap the turbo commands for nx equivalents, such as nx affected, in the generator before downloading.

Where do environment variables go in a monorepo?

In each app, not the root, and declared in turbo.json so cache keys include them. The no-secrets rule still applies everywhere.

Are these Turborepo monorepo files free to use?

Yes. Copy them into any project, commercial or not, without attribution. They are a starting point: adjust the commands and rules to match your repository.

How Can You Verify That Nothing Leaves This Browser?

You do not have to take our word for it. Developer tools show every request a page makes, so you can watch this page work and confirm that nothing you type is sent. The check takes under a minute.

  1. Open your browser developer tools with F12, or Cmd+Option+I on a Mac, and select the Network tab.
  2. Reload the page and let it finish. You will see the page's own files, its web fonts, and one anonymous page-view request. Nothing has been typed yet, so none of them can contain your input.
  3. Click the clear icon in the Network tab so that the log is empty.
  4. Switch between the file tabs, copy a file and download the zip.
  5. Look at the Network tab again. It is still empty. Downloads are built in the page as Blob URLs, so even the zip never touches a server. For extra proof, turn on offline mode after the page loads: everything keeps working.

Only the feedback form can add a line to that log, and it sends only the vote and comment you type into it. 2prompt has no server code at all: no API, no model and no database of your files. The production site also sends a Content-Security-Policy header that tells your browser to refuse connections to anywhere except this site, the fonts and the anonymous analytics endpoint.

Was this helpful?