commit 0b48e618d8e9b7fc75c8b90b79d3af7b023fd6f3
Author: Leon Tsao <leocaoxiaozhu@163.com>
Date:   Fri Jun 12 15:38:54 2026 +0800

    docs: add README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b75eb8f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+# TokenLens
+
+TokenLens is a local token usage dashboard for macOS. It tracks the usage of AI models like Claude, Codex, and Gemini.
+
+## Features
+
+- **Local Dashboard:** Monitor your token usage locally on macOS.
+- **Model Support:** Tracks usage across popular models including Claude, Codex, and Gemini.
+- **Modern Stack:** Built with Electron, React, TypeScript, and Vite.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js
+- npm (or yarn/pnpm)
+
+### Installation
+
+1. Clone the repository:
+   ```bash
+   git clone <repository-url>
+   ```
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+### Development
+
+To start the Vite development server:
+```bash
+npm run dev
+```
+
+To run the Electron app in development mode:
+```bash
+npm run electron:dev
+```
+
+### Build
+
+To build the project for production:
+```bash
+npm run build
+```
+
+To package the application (creates a macOS DMG):
+```bash
+npm run dist
+```
+
+## Running Tests
+
+To run the test suite:
+```bash
+npm run test
+```
+
+## Technologies Used
+
+- [Electron](https://www.electronjs.org/)
+- [React](https://reactjs.org/)
+- [Vite](https://vitejs.dev/)
+- [TypeScript](https://www.typescriptlang.org/)
+- [Lucide React](https://lucide.dev/)