KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

offercatcher

★ 23 Open GitHub ↗

🎯 AI 驱动的招聘邮件提醒工具，自动提取面试、测评、笔试等事件并同步到 Apple Reminders。Never miss an interview again.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Never miss an interview again. 
 Turn recruiting emails into native reminders with AI-powered parsing.

<a href="#features">Features</a> •
 <a href="#quick-start">Quick Start</a> •
 <a href="#installation">Installation</a> •
 <a href="#usage">Usage</a> •
 <a href="#configuration">Configuration</a>

---

## The Problem

You're job hunting. Your inbox is flooded with recruiting emails—interview invites, online assessments, coding challenges, deadlines. The important ones get buried under "application received" receipts and spam.

**You miss an interview.** Or show up at the wrong time. Or forget that coding test deadline.

## The Solution

**OfferCatcher** automatically scans your emails, extracts recruiting events using AI, and syncs them into native reminders on your iPhone/Mac.

```
📧 Email arrives → 🤖 AI parses it → 🔔 Reminder created
```

No regex. No brittle pattern matching. Just intelligent extraction that works across all email formats and languages.

## Architecture

OfferCatcher is intentionally split into two layers:

- **OpenClaw orchestration** handles scanning Apple Mail, calling the LLM, validating event JSON, and deciding what should be synced.
- **Native bridge execution** handles the final reminder write. `scripts/apple_reminders_bridge.py` prefers `remindctl` (Swift + EventKit) and only falls back to AppleScript when needed.

This design avoids relying on a background Node process directly automating `Reminders.app`, which can be unreliable under macOS TCC / Automation permissions.

## Features

- **🤖 AI-Powered Parsing** — LLM understands any email format, any language
- **🍎 Native Apple Integration** — Works with Mail.app and Reminders.app
- **📱 Cross-Device Sync** — Reminders appear on iPhone, iPad, Mac via iCloud
- **⚡ Fully Automated** — Set up once, runs via OpenClaw heartbeat
- **🌍 Universal Language Support** — Chinese, English, Japanese, you name it

## Community

- [LINUX DO](https://linux.do) — 中文开发者社区

## Quick Start

```bash
# Install
curl -sSL https://raw.githubusercontent.com/NissonCX/offercatcher/main/install.sh | bash

# Recommended native bridge
brew install steipete/tap/remindctl
remindctl authorize

# Configure
echo 'mail_account: "Gmail"' >> ~/.openclaw/offercatcher.yaml

# Scan
python3 ~/.openclaw/workspace/skills/offercatcher/scripts/recruiting_sync.py --scan-only
```

OpenClaw will automatically parse the results and create reminders.

## Installation

### Requirements

- macOS (Apple Mail & Reminders integration)
- Python 3.11+
- `remindctl` recommended (`brew install steipete/tap/remindctl`)
- [OpenClaw](https://github.com/NissonCX/openclaw) (optional, for automation)

### Option 1: Install from ClawHub (Recommended)

```bash
# Search for the skill
openclaw skills search offercatcher

# Install to your workspace
openclaw skills install offercatcher
```

### Option 2: One-Line Install

```bash
curl -sSL https://raw.githubusercontent.com/NissonCX/offercatcher/main/install.sh | bash
```

Then authorize the native bridge once:

```bash
remindctl authorize
```

### Option 3: Manual Install

```bash
git clone https://github.com/NissonCX/offercatcher.git
cd offercatcher
```

## Usage

### Step 1: Find Your Mail Account

```bash
python3 scripts/list_mail_sources.py
```

This shows all accounts configured in Apple Mail:

```json
[
  {"account": "Gmail", "mailbox": "INBOX"},
  {"account": "iCloud", "mailbox": "INBOX"}
]
```

### Step 2: Configure

Create `~/.openclaw/offercatcher.yaml`:

```yaml
mail_account: "Gmail"    # Your Apple Mail account name
mailbox: "INBOX"         # Mailbox to scan
days: 2                  # Scan last N days
max_results: 60          # Max emails to process
```

### Step 3: Scan Emails

```bash
python3 scripts/recruiting_sync.py --scan-only
```

Output (JSON for OpenClaw LLM to parse):

```json
{
  "emails": [
    {
      "message_id": "12345",
      "subject": "Interview Invitation - Software Engineer",
      "sender": "recruiting@company.com",
      "received_at": "2026-04-01 10:00",
      "body": "Dear Candidate, Your interview is scheduled for..."
    }
  ]
}
```

### Step 4: AI Parsing + Reminder Creation

OpenClaw automatically:
1. Parses each email with LLM
2. Extracts company, event type, time, link
3. Hands the final write to the native reminders bridge

Or manually apply parsed events:

```bash
python3 scripts/recruiting_sync.py --apply-events /tmp/events.json
```

### Manual Event Entry

```bash
python3 scripts/manual_event.py \
  --title "Google Interview" \
  --due "2026-04-15 14:00" \
  --notes "Link: https://meet.google.com/xxx"
```

## How It Works

```
┌─────────────────┐     ┌─────────────────┐     ┌────────────────────────────┐
│   --scan-only   │ ──▶ │   OpenClaw LLM  │ ──▶ │  Native bridge writes      │
│   Scan emails   │     │   Parse events  │     │  remindctl / AppleScript   │
└─────────────────┘     └─────────────────┘     └────────────────────────────┘
```

### Why LLM Over Regex?

| Regex | LLM |
|-------|-----|
| Breaks on new formats | Adapts to any format |
| Company-specific rules | Works for any company |
| Manual maintenance | Zero maintenance |
| Language-specific | Universal language support |

## Configuration

### Command Line Options

| Option | Default | Description |
|--------|---------|-------------|
| `--mail-account` | all | Apple Mail account name |
| `--mailbox` | INBOX | Mailbox folder to scan |
| `--days` | 2 | Scan last N days |
| `--max-results` | 60 | Max emails to process |
| `--dry-run` | false | Test without creating reminders |
| `--verbose` | false | Enable debug logging |

### Environment Variables

```bash
OFFERCATCHER_MAIL_ACCOUNT="Gmail"
OFFERCATCHER_DAYS=7
OFFERCATCHER_MAX_RESULTS=100
OFFERCATCHER_LOG_LEVEL=DEBUG
```

### Event JSON Format

The `--apply-events` command accepts:

```json
{
  "events": [
    {
      "id": "unique-id",
      "company": "Google",
      "event_type": "interview",
      "title": "Google SWE Interview",
      "timing": {"start": "2026-04-15 14:00", "end": "2026-04-15 15:00"},
      "role": "Software Engineer",
      "link": "https://meet.google.com/xxx"
    }
  ]
}
```

Event types: `interview`, `ai_interview`, `written_exam`, `assessment`, `authorization`, `deadline`

## Screenshots

<table>
 <tr>
 <td align="center">
 <img src="./assets/showcase-list.jpg" alt="Reminder list" width="260">
 Reminder List
 </td>
 <td align="center">
 <img src="./assets/showcase-detail.jpg" alt="Reminder detail" width="260">
 Reminder Detail
 </td>
 </tr>
</table>

## Project Structure

```
offercatcher/
├── scripts/
│   ├── recruiting_sync.py      # Main script (scan/apply)
│   ├── apple_reminders_bridge.py # Apple Reminders bridge
│   ├── manual_event.py         # Manual event entry
│   └── list_mail_sources.py    # List Mail accounts
├── tests/                      # Unit tests
├── SKILL.md                    # OpenClaw skill definition
└── README.md                   # This file
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

[MIT License](./LICENSE)

---

Made with ❤️ for job seekers everywhere

offercatcher

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README