diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c0335f5
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,39 @@
+# ants-simulation
+
+GPU-accelerated ant colony simulation. ants navigate via pheromone trails, all computed in GLSL fragment shaders rendered to offscreen textures.
+
+## stack
+
+- three.js — WebGL renderer, render targets, shader materials
+- lil-gui — runtime parameter tweaking
+- vite — dev server and build
+- typescript
+- GLSL (raw .frag/.vert files loaded as strings via vite plugin)
+
+## architecture
+
+all simulation logic runs on the GPU via ping-pong render targets:
+
+- `AntsComputeScene` — per-ant state (position, direction, scent storage) computed each frame
+- `AntsDiscretizeScene` — maps continuous ant positions to discrete world grid cells
+- `WorldComputeScene` — updates world pheromone grid based on ant deposits
+- `WorldBlurScene` — diffuses pheromones across neighboring cells
+- `DrawScene` — handles user painting (food, home, obstacles, erase)
+- `ScreenScene` — final composited output with camera controls
+
+`Renderer.ts` orchestrates the render pass order and manages all WebGLRenderTargets.
+`Config.ts` holds simulation parameters exposed through lil-gui.
+
+## commands
+
+- `bun run dev` — start dev server
+- `bun run build` — production build to `build/`
+- `bun run preview` — preview production build
+
+## shader files
+
+in `src/shaders/`. each scene has a matched .vert/.frag pair. loaded as raw strings by the vite glsl plugin in `vite.config.ts`.
+
+## textures
+
+in `public/textures/` — ant.png and food.png sprites.