diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d61aec4
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Gitea Git server setup using Docker Compose with PostgreSQL database. The repository includes configuration files and helper scripts for managing the service.
+
+## Architecture
+
+**Services:**
+- `gitea` - Gitea web application container (gitea/gitea:latest)
+- `db` - PostgreSQL 14 database
+
+**Network:** Both services communicate via a dedicated `gitea` network.
+
+**Data Persistence:**
+- `./data` - Gitea application data (repositories, config, uploads)
+- `./postgres` - PostgreSQL database data
+
+**Ports:**
+- Web UI: 31337 (mapped to container port 3000)
+- SSH Git: 31338 (mapped to container port 22)
+
+**Database Configuration:**
+- Type: PostgreSQL
+- Host: db:5432 (internal docker network)
+- Database: gitea
+- User/Password: gitea/gitea
+- Configured via environment variables in docker-compose.yml
+
+## Common Commands
+
+**Service Management:**
+```bash
+./start.sh          # Start services
+./stop.sh           # Stop services
+docker-compose logs -f          # View logs
+docker-compose restart          # Restart services
+```
+
+**Git Workflow:**
+```bash
+./push.sh "message"     # Add, commit, and push to remote
+git push                # Push directly (if already committed)
+```
+
+**Backup:**
+```bash
+tar -czf gitea-backup-$(date +%Y%m%d).tar.gz data/
+```
+
+## Remote Setup
+
+The git repository has a remote configured at:
+- `root@192.168.88.81:/mnt/mydata/gitea` (bare repository)
+- Working directory syncs to `/mnt/mydata/gitea-www` via post-receive hook
+- HEAD points to `refs/heads/main` (not master)
+
+When pushing to the remote, a post-receive hook automatically checks out files to the working directory.
+
+## Important Notes
+
+- The `.gitignore` excludes `data/` directory only (not `postgres/`)
+- Scripts are executable and use bash shebang
+- All data directories are local mounts for easy backup
+- Container runs with UID/GID 1000 for file permissions