{"_id":"@aayvyas/gmail-classifier","_rev":"5-76f38ddcb39a4815e982b381eea84c3a","name":"@aayvyas/gmail-classifier","dist-tags":{"latest":"0.0.3"},"versions":{"0.0.2":{"name":"@aayvyas/gmail-classifier","version":"0.0.2","keywords":["gmail","email","classifier","ai","llm","local","privacy","automation","inbox","organization","genai","llama","ollama"],"author":{"name":"aayvyas"},"license":"MIT","_id":"@aayvyas/gmail-classifier@0.0.2","maintainers":[{"name":"aayvyas","email":"aayushbrajeshvyas@gmail.com"}],"homepage":"https://github.com/aayvyas/gmail-classifier#readme","bugs":{"url":"https://github.com/aayvyas/gmail-classifier/issues"},"bin":{"gmail-classifier":"dist/index.js"},"dist":{"shasum":"ccd4ab1e5489e032102348432a65f1411ec92922","tarball":"https://registry.npmjs.org/@aayvyas/gmail-classifier/-/gmail-classifier-0.0.2.tgz","fileCount":10,"integrity":"sha512-Ebe4nkb3Xa4LV5HJREASXBWpXHIU5UFvTTPN9Uljavti5OMmQDOtF23xMstgjWZ8nYUeY8ZPhgxxR1GxpdI/yA==","signatures":[{"sig":"MEYCIQCmZNYo2P1+i8pCFj/9msDagklHozII3xCEadZoTGXzBwIhALE7jSZTkMy/RrPv2ZoaeUI1cx8PeZZJt7DT9M2fJoiG","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22487},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"ac6af72df79eb50be0bfaf52bd00de29c4f10f9f","scripts":{"dev":"ts-node src/index.ts","test":"echo \"Error: no test specified\" && exit 1","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"aayvyas","email":"aayushbrajeshvyas@gmail.com"},"repository":{"url":"git+https://github.com/aayvyas/gmail-classifier.git","type":"git"},"_npmVersion":"10.9.2","description":"Privacy-focused Gmail classifier using local LLM - automatically organize your inbox with AI","directories":{},"_nodeVersion":"22.14.0","dependencies":{"dotenv":"^17.2.3","openai":"^6.9.0","ts-node":"^10.9.2","node-cron":"^4.2.1","googleapis":"^166.0.0","@google-cloud/local-auth":"^3.0.1"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^24.10.1","@types/node-cron":"^3.0.11"},"_npmOperationalInternal":{"tmp":"tmp/gmail-classifier_0.0.2_1763730709759_0.21023270279410355","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@aayvyas/gmail-classifier","version":"0.0.3","description":"Privacy-focused Gmail classifier using local LLM - automatically organize your inbox with AI","main":"dist/index.js","types":"dist/index.d.ts","bin":{"gmail-classifier":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"ts-node src/index.ts","prepublishOnly":"npm run build","test":"echo \"Error: no test specified\" && exit 1"},"keywords":["gmail","email","classifier","ai","llm","local","privacy","automation","inbox","organization","genai","llama","ollama"],"author":{"name":"aayvyas"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aayvyas/gmail-classifier.git"},"bugs":{"url":"https://github.com/aayvyas/gmail-classifier/issues"},"homepage":"https://github.com/aayvyas/gmail-classifier#readme","engines":{"node":">=18.0.0"},"devDependencies":{"@types/node":"^24.10.1","@types/node-cron":"^3.0.11","typescript":"^5.9.3"},"dependencies":{"@google-cloud/local-auth":"^3.0.1","dotenv":"^17.2.3","googleapis":"^166.0.0","node-cron":"^4.2.1","openai":"^6.9.0","ts-node":"^10.9.2"},"_id":"@aayvyas/gmail-classifier@0.0.3","gitHead":"ac6af72df79eb50be0bfaf52bd00de29c4f10f9f","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-Ly/cdiRL5s40pjotYuxvJfcjbuKgVUpas8BHAc8vwytw4/QQrljOtGGCo6+emnN5tovObeY60X1DxYtBtqwLSA==","shasum":"106a6cddfa93488293df86d13a0949c5617baaf3","tarball":"https://registry.npmjs.org/@aayvyas/gmail-classifier/-/gmail-classifier-0.0.3.tgz","fileCount":10,"unpackedSize":22486,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICgOyjcqY1A+DKdmgFgnmrA+yytR27onotcsmcBjopYsAiEA9EnF4fUPbrq2CBAEhXx1xWsu0/Bbbpjnm3XCXGaoGwM="}]},"_npmUser":{"name":"aayvyas","email":"aayushbrajeshvyas@gmail.com"},"directories":{},"maintainers":[{"name":"aayvyas","email":"aayushbrajeshvyas@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gmail-classifier_0.0.3_1763731424793_0.4716740488661819"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-21T13:11:49.671Z","modified":"2025-11-21T13:23:45.179Z","0.0.1":"2025-11-21T12:52:09.613Z","0.0.2":"2025-11-21T13:11:49.961Z","0.0.3":"2025-11-21T13:23:44.992Z"},"bugs":{"url":"https://github.com/aayvyas/gmail-classifier/issues"},"author":{"name":"aayvyas"},"license":"MIT","homepage":"https://github.com/aayvyas/gmail-classifier#readme","keywords":["gmail","email","classifier","ai","llm","local","privacy","automation","inbox","organization","genai","llama","ollama"],"repository":{"type":"git","url":"git+https://github.com/aayvyas/gmail-classifier.git"},"description":"Privacy-focused Gmail classifier using local LLM - automatically organize your inbox with AI","maintainers":[{"name":"aayvyas","email":"aayushbrajeshvyas@gmail.com"}],"readme":"# 📧 Local Gmail Classifier with AI\n\n> **Classify your Gmail inbox using a local LLM (Llama 3, Gemma, etc.) - 100% Privacy-Focused.**\n\n[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-18+-green)](https://nodejs.org/)\n\nThis project automates email organization by fetching unread emails from your Gmail, analyzing them with a **locally running Large Language Model (LLM)**, and applying granular labels automatically. No email data leaves your machine for classification!\n\n## ✨ Features\n\n*   **🔒 Privacy First**: Uses a local LLM server (e.g., via `llama.cpp` or Ollama). Your emails are not sent to OpenAI or Anthropic.\n*   **🏷️ Granular Classification**: Automatically categorizes emails into:\n    *   `bank-alert`, `finance`, `payments`\n    *   `job-application`, `interview`, `coding-assessment`\n    *   `newsletter`, `promotions`, `spam`\n    *   `social`, `travel`, `shopping`\n    *   ...and more!\n*   **🤖 Smart & Context-Aware**: Uses the email subject, snippet, and body to determine the best label.\n*   **⏱️ Automated**: Runs as a background cron job (default: every 5 minutes).\n*   **🛠️ Easy Management**: Includes a CLI helper to start/stop/monitor the service.\n\n## 🚀 Prerequisites\n\n1.  **Node.js**: v18 or higher.\n2.  **Local LLM Server**:\n    *   You need an LLM running locally that accepts OpenAI-compatible requests.\n    *   Default URL: `http://localhost:12434/engines/llama.cpp/v1`\n    *   *Tip: You can use [Ollama](https://ollama.com/) or [LocalAI](https://localai.io/). If using Ollama, you might need a proxy or ensure it exposes the OpenAI compatible endpoint.*\n3.  **Google Cloud Project**:\n    *   Enable the **Gmail API**.\n    *   Create **OAuth 2.0 Desktop App** credentials.\n    *   Download the `credentials.json` file.\n\n## 🛠️ Installation & Setup\n### 1. Clone the Repository\n```bash\ngit clone https://github.com/yourusername/gmail-classifier.git\ncd gmail-classifier\n```\n\n### 2. Install Dependencies\n```bash\nnpm install\n```\n\n### 3. Configure Environment Variables (Required)\nCreate a `.env` file in the project root based on the example:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your settings:\n\n```ini\n# LLM Configuration\nLLM_BASE_URL=http://localhost:12434/engines/llama.cpp/v1\nLLM_API_KEY=sk-local-key\nLLM_MODEL=ai/gemma3\n\n# Cron Schedule (Default: Every 5 minutes)\nCRON_SCHEDULE=*/5 * * * *\n```\n\n**Note:** The application will fail to start if `LLM_BASE_URL` or `LLM_MODEL` are missing.\n\n### 4. Configure Credentials\nPlace your downloaded `credentials.json` file in the root directory of the project.\n```bash\n# It should look like this\nls -F\ncredentials.json  .env  package.json  src/ ...\n```\n\n## 🏃‍♂️ Usage\n\n### First Run (Authentication)\nThe first time you run the app, it will open your browser to authenticate with Google.\n```bash\nnpx ts-node src/index.ts\n```\n\n### Running as a Service (Recommended)\nWe provide a handy zsh helper script to manage the classifier as a background service.\n\n1.  **Add to your shell**:\n    Add the following to your `~/.zshrc` (or `~/.bashrc`):\n    ```bash\n    # Optional: Set custom project path if not in default location\n    # export GMAIL_CLASSIFIER_DIR=\"/path/to/gmail-classifier\"\n    \n    source /path/to/gmail-classifier/service.zsh\n    ```\n\n2.  **Reload shell**:\n    ```bash\n    source ~/.zshrc\n    ```\n\n3.  **Commands**:\n    ```bash\n    gmail-classifier start   # 🚀 Start the background service\n    gmail-classifier status  # 🔍 Check if running\n    gmail-classifier log     # 📄 View real-time logs\n    gmail-classifier stop    # 🛑 Stop the service\n    ```\n\n## ⚙️ Customization\n\n### Modifying Labels\nEdit `src/prompts.ts` to add or remove categories. The system will automatically create new labels in Gmail if they don't exist.\n\n```typescript\nexport const getLabels = (): string[] => {\n  return [\n    \"urgent\",\n    \"family\",\n    // ... add your own\n  ];\n};\n```\n\n### Adjusting the Prompt\nYou can tweak the system prompt in `src/prompts.ts` to better suit your specific needs or to give the LLM more context about how you like things filed.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1.  Fork the project\n2.  Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3.  Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4.  Push to the branch (`git push origin feature/AmazingFeature`)\n5.  Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the ISC License - see the `package.json` file for details.\n","readmeFilename":"README.md"}