diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4f8bc13
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Hako is a Docker container management tool designed specifically for Claude Code. It provides sandboxed environments to prevent Claude from accidentally affecting files outside the current working directory.
+
+## Architecture
+
+- **main.go**: CLI entry point using Cobra framework with commands: init, up, down, ps, sync
+- **commands.go**: Command implementations that orchestrate Docker operations and file syncing
+- **docker.go**: Core Docker operations (image building, container lifecycle, file copying)
+- **git.go**: Git integration for project detection and container naming
+- **utils.go**: Utility functions for command execution with logging to stderr
+
+## Key Design Patterns
+
+- Container names follow pattern: `hako-{language}-{project}-{subdirs}` (sanitized, max 60 chars)
+- All Docker commands are logged to stderr for transparency
+- File syncing respects .gitignore and excludes .git directory for security
+- Images are versioned (HAKO-VERSION=1) for upgrade management
+
+## Development Commands
+
+Build and run:
+```bash
+go run . <command>
+```
+
+Build binary:
+```bash
+go build -o hako
+```
+
+## Core Workflows
+
+1. **Image Management**: Base image (hako-userland) + language variants (hako-userland-{lang})
+2. **Container Lifecycle**: Create → Start → Copy workspace → Enter shell
+3. **File Syncing**: Uses git ls-files to copy only tracked/untracked (non-ignored) files
+4. **Project Isolation**: Must run within git repositories, containers scoped to project+path
+
+## Configuration
+
+- Base Dockerfile stored in `~/.config/hako/Dockerfile.base`
+- Language Dockerfiles in `~/.config/hako/Dockerfile.{lang}`
+- Mounts Claude config directory/file if present for seamless integration
\ No newline at end of file