diff --git a/README.md b/README.md
new file mode 100644
index 0000000..efaa57f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,99 @@
+# OpenChamber
+
+OpenChamber 是一个基于 Web 的 AI 编程助手界面，用于与 OpenCode 服务器交互。
+
+## 快速开始
+
+### 使用单文件 exe（推荐）
+
+直接下载 `OpenChamber.exe`，双击运行：
+
+```bash
+# 默认端口 3000
+OpenChamber.exe
+
+# 指定端口
+OpenChamber.exe --port 8080
+
+# 查看帮助
+OpenChamber.exe --help
+```
+
+启动后访问 http://localhost:3000
+
+### 从源码运行
+
+需要安装 [Bun](https://bun.sh) 或 Node.js 20+
+
+```bash
+# 安装依赖
+bun install
+
+# 构建前端
+bun run build
+
+# 启动服务器
+bun server/index.js --port 3000
+```
+
+## 构建单文件 exe
+
+```bash
+cd web
+bun run build:exe
+```
+
+输出：`web/OpenChamber.exe`（约 320MB）
+
+详细文档：[docs/single-file-exe-build.md](docs/single-file-exe-build.md)
+
+## 项目结构
+
+```
+├── ui/                 # 前端组件库
+├── web/
+│   ├── src/           # 前端源码
+│   ├── server/        # 后端服务器
+│   ├── bin/           # CLI 工具
+│   └── dist/          # 构建输出
+├── docs/              # 文档
+└── AGENTS.md          # AI Agent 参考文档
+```
+
+## 常用命令
+
+```bash
+# 开发模式
+bun run dev                    # 前端热更新
+bun run dev:server             # 启动开发服务器
+
+# 构建
+bun run build                  # 构建前端
+bun run build:exe              # 构建单文件 exe
+
+# 代码检查
+bun run type-check:web         # TypeScript 类型检查
+bun run lint:web               # ESLint 检查
+```
+
+## 依赖
+
+- [Bun](https://bun.sh) - 运行时和打包工具
+- [React](https://react.dev) - 前端框架
+- [Express](https://expressjs.com) - 后端服务器
+- [Tailwind CSS](https://tailwindcss.com) - 样式框架
+
+## 配置
+
+### 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `OPENCHAMBER_PORT` | 服务器端口（默认 3000） |
+| `OPENCODE_HOST` | 外部 OpenCode 服务器地址 |
+| `OPENCODE_PORT` | 外部 OpenCode 端口 |
+| `OPENCODE_SKIP_START` | 跳过启动 OpenCode |
+
+## 许可证
+
+MIT
\ No newline at end of file