diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..47d3c61
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,143 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## 项目概述
+
+这是一个基于 WXT 框架的浏览器扩展项目，提供测试工具功能，包括时间戳转换等。
+
+## 核心命令
+
+### 开发相关
+
+- `npm run dev` - 启动 Chrome 浏览器的开发模式
+- `npm run dev:firefox` - 启动 Firefox 浏览器的开发模式
+- `npm run build` - 构建 Chrome 浏览器的生产版本
+- `npm run build:firefox` - 构建 Firefox 浏览器的生产版本
+- `npm run zip` - 打包 Chrome 扩展
+- `npm run zip:firefox` - 打包 Firefox 扩展
+- `npm run compile` - TypeScript 类型检查（不生成文件）
+- `npm run lint` - 运行 ESLint 检查
+
+### 测试相关
+
+- `npm run test` - 运行所有测试（单次执行）
+- `npm run test:watch` - 运行测试并监听文件变化
+- `npm run test:coverage` - 运行测试并生成覆盖率报告
+
+**运行单个测试文件：**
+
+```bash
+npx vitest run components/__tests__/CopyButton.test.tsx
+```
+
+**测试技术栈：**
+
+- Vitest - 测试框架
+- @testing-library/react - React 组件测试
+- @testing-library/user-event v13 - 用户交互模拟（注意：v13 不支持 setup()，使用 fireEvent）
+- jsdom - 浏览器环境模拟
+
+### 依赖与准备
+
+- `npm install` - 安装依赖
+- `postinstall` 会自动运行 `wxt prepare` 准备开发环境
+- `prepare` 钩子会初始化 Husky Git 钩子
+
+## 项目架构
+
+### 技术栈
+
+- **框架**: WXT (Web Extension Toolkit) - 浏览器扩展开发框架
+- **前端**: React 19 + TypeScript
+- **UI 库**: Material UI (MUI)
+- **状态管理**: React Hooks
+- **路由**: React Router DOM
+
+### 目录结构
+
+```
+├── components/           # 可复用 UI 组件
+│   ├── CopyButton.tsx           # 复制按钮组件
+│   ├── DatetimeToTimestamp.tsx   # 日期转时间戳组件
+│   ├── Navbar.tsx                # 导航栏组件
+│   ├── RoutePersistence.tsx      # 路由持久化组件
+│   ├── TimestampExecution.tsx    # 时间戳执行组件
+│   └── TimestampToDatetime.tsx   # 时间戳转日期组件
+├── entrypoints/          # 浏览器扩展入口点
+│   ├── background.ts     # 后台脚本（主进程）
+│   ├── content.ts        # 内容脚本（注入到页面）
+│   └── popup/            # 扩展弹窗界面
+│       ├── App.tsx       # 弹窗主应用
+│       ├── main.tsx      # 弹窗入口
+│       └── pages/        # 弹窗页面
+│           ├── TestPage.tsx      # 测试页面
+│           └── TimestampPage.tsx # 时间戳工具页面
+├── utils/                # 工具函数
+│   ├── chromeStorage.ts  # Chrome 存储工具
+│   ├── dayjs.ts          # 日期处理工具
+│   └── messages.tsx      # 消息通信工具
+├── types/                # 类型定义
+│   └── storage.d.ts      # 存储相关类型
+```
+
+### 核心功能实现
+
+#### 1. 时间戳转换工具
+
+- 位置: `components/` 目录下的时间戳相关组件
+- 依赖: dayjs 库进行日期处理
+- 功能: 支持日期与时间戳的双向转换，支持多种格式
+
+#### 2. 通信系统
+
+- 位置: `utils/messages.tsx`
+- 机制: 使用 `@webext-core/messaging` 库实现
+- 通信通道: 后台脚本 ↔ 内容脚本 ↔ 弹窗
+
+#### 3. 数据存储
+
+- Chrome Storage API: `utils/chromeStorage.ts` (用于配置等小数据)
+
+### 关键配置文件
+
+#### wxt.config.ts
+
+- 配置 WXT 框架参数
+- 启用 React 模块
+- 配置浏览器扩展权限
+- Vite 构建配置（使用 Terser 压缩，强制 ASCII 编码）
+
+#### manifest 权限
+
+```typescript
+permissions: [
+  'storage',           // 存储权限
+  'unlimitedStorage',  // 无限制存储
+  'clipboardWrite',    // 剪贴板写入
+  'activeTab',         // 当前标签页
+  'scripting',         // 脚本注入
+  'tabs',              // 标签页管理
+  'debugger',          // 调试器
+],
+host_permissions: ['<all_urls>']  // 访问所有网站
+```
+
+## 开发注意事项
+
+### 扩展入口点
+
+- **后台脚本**: `entrypoints/background.ts` - 处理扩展生命周期和后台任务
+- **内容脚本**: `entrypoints/content.ts` - 注入到网页中，处理 DOM 交互
+- **弹窗**: `entrypoints/popup/main.tsx` - 用户点击扩展图标时显示
+
+### 浏览器兼容性
+
+- 支持 Chrome 和 Firefox 浏览器
+- 使用 WXT 框架抽象浏览器差异
+
+### 代码质量
+
+- 使用 ESLint 进行代码检查
+- Husky 用于 Git 钩子管理
+- Lint-staged 确保暂存文件符合规范