diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..764b35112
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,97 @@
+# AGENTS.md
+
+This file provides guidance for AI coding agents working in this repository.
+
+## Project overview
+
+Umami is a privacy-focused web analytics platform built with Next.js 15, React 19, and TypeScript.
+
+- Primary database: PostgreSQL
+- Optional analytics backend: ClickHouse
+- Optional cache/session backend: Redis
+
+## Development rules
+
+- Assume a dev server is already running on port `3001`.
+- Do **not** start another dev server.
+- Use `pnpm` (not `npm` or `yarn`).
+- Avoid destructive shell commands unless explicitly requested.
+- Ask before running `git commit` or `git push`.
+
+## Common commands
+
+```bash
+# Development
+pnpm dev
+pnpm build
+pnpm start
+
+# Database
+pnpm build-db
+pnpm update-db
+pnpm check-db
+pnpm seed-data
+
+# Code quality
+pnpm lint
+pnpm format
+pnpm check
+pnpm test
+
+# Build specific parts
+pnpm build-tracker
+pnpm build-geo
+```
+
+## Architecture
+
+- `src/app/`: Next.js App Router routes and API endpoints
+- `src/components/`: UI components and hooks
+- `src/lib/`: shared utilities and infrastructure helpers
+- `src/queries/`: data access layer (Prisma + raw SQL)
+- `src/store/`: Zustand stores
+- `src/tracker/`: standalone client tracking script
+- `prisma/`: schema and migrations
+
+## Key implementation patterns
+
+### API request validation
+
+Use Zod + `parseRequest` in API handlers:
+
+```ts
+const schema = z.object({ /* fields */ });
+const { body, error } = await parseRequest(request, schema);
+if (error) return error();
+```
+
+### Authentication
+
+- JWT via `Authorization: Bearer <token>`
+- Share token via `x-umami-share-token`
+- Role model: `admin`, `manager`, `user`
+
+### Client data fetching
+
+- React Query defaults: `staleTime` 60s, no retry, no refetch on window focus
+
+### Styling
+
+- CSS Modules with CSS variables and theme support
+
+## Environment variables
+
+Common env vars:
+
+- `DATABASE_URL`
+- `APP_SECRET`
+- `CLICKHOUSE_URL`
+- `REDIS_URL`
+- `BASE_PATH`
+- `DEBUG`
+
+## Runtime requirements
+
+- Node.js 18.18+
+- PostgreSQL 12.14+
+- `pnpm`