diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..00faaf81c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,23 @@
+# Agent Development Guide
+
+A file for [guiding coding agents](https://agents.md/).
+
+## Commands
+
+- **Build:** `zig build`
+- **Test (Zig):** `zig build test`
+- **Test filter (Zig)**: `zig build test -Dtest-filter=<test name>`
+- **Formatting (Zig)**: `zig fmt .`
+- **Formatting (other)**: `prettier -w .`
+
+## Directory Structure
+
+- Shared Zig core: `src/`
+- C API: `include/ghostty.h`
+- macOS app: `macos/`
+- GTK (Linux and FreeBSD) app: `src/apprt/gtk-ng`
+
+## macOS App
+
+- Do not use `xcodebuild`
+- Use `zig build` to build the macOS app and any shared Zig code