diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..55cf301
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Docker image for running Samba file server, forked from dperson/samba. It provides an Alpine-based container with current Samba versions and macOS Time Machine support.
+
+## Build and Run Commands
+
+```bash
+# Build the Docker image
+docker build -t samba .
+
+# Run with default configuration
+docker run -it -p 139:139 -p 445:445 -d samba -p
+
+# Run with docker-compose (uses example configuration)
+docker-compose up -d
+
+# Test the running container
+smbclient -L \\localhost -U % -m SMB3
+```
+
+## Architecture
+
+### Key Files
+
+- **Dockerfile**: Alpine-based image that installs samba and configures `/etc/samba/smb.conf` with sensible defaults (SMB2/3 only, Time Machine support, recycle bin)
+- **samba.sh**: Entrypoint script that handles all configuration via CLI flags and environment variables
+
+### Configuration Flow
+
+1. Container starts with `samba.sh` as entrypoint (via tini)
+2. Environment variables (SHARE, USER, GLOBAL, etc.) are processed first
+3. CLI flags (-s, -u, -g, etc.) override/add to configuration
+4. Configuration is written to `/etc/samba/smb.conf`
+5. `smbd` starts in foreground mode
+
+### Configuration Options
+
+Configuration can be done via CLI flags or environment variables:
+- `-s` / `SHARE`: Add shares (format: `name;/path;browse;readonly;guest;users;admins;writelist;comment`)
+- `-u` / `USER`: Add users (format: `username;password;ID;group;GID`)
+- `-g` / `GLOBAL`: Set global smb.conf options
+- `-G` / `GENERIC`: Set section-specific smb.conf options
+- `-n` / `NMBD`: Enable NetBIOS daemon (requires ports 137-138/udp)
+- `-p` / `PERMISSIONS`: Fix ownership/permissions on shares
+
+Multiple shares/users: use numbered env vars (SHARE, SHARE2, SHARE3, etc.)
+
+### Exposed Ports
+
+- 137/udp, 138/udp: NetBIOS (only needed with `-n` flag)
+- 139/tcp: SMB over NetBIOS
+- 445/tcp: SMB direct
+
+### Default User
+
+Samba runs as `smbuser:smb` by default. Override with `USERID` and `GROUPID` environment variables.