Personal AI Employee

Hackathon Tier: Platinum | All 7 Capabilities Live

A hybrid cloud-local autonomous AI agent that monitors multiple sources (filesystem, Gmail, WhatsApp), processes tasks through a git-synced Obsidian vault pipeline, and executes actions via MCP servers with human-in-the-loop safety gates. The cloud VM (Ubuntu 24.04) works 24/7 even when your laptop is off — detecting events, drafting responses, and queueing approval requests. When you come back online, review and approve with a single file move. Built for the 2026 Personal AI Employee Hackathon.

• Filesystem watcher (Watchdog) monitors ~/Desktop/DropForAI
• Creates metadata .md files in Needs_Action/ with YAML frontmatter
• 3 Claude Code skills: vault-interact, process-needs-action, check-and-process-needs-action
• Routes by risk: routine → Done/, sensitive/critical → Pending_Approval/

• 4 watchers: filesystem, Gmail (OAuth2), WhatsApp (Playwright), daily scheduler (APScheduler)
• Central orchestrator: priority queue, batch processing, HITL routing
• Action executor: importlib-based function dispatch with approval gates
• Ralph Wiggum retry loop: exponential backoff for fault tolerance
• PM2 process management

• 4 MCP servers via FastMCP (stdio transport):
  • fte-email — Gmail draft/send/search (sensitive HITL)
  • fte-social — Facebook/Instagram/Twitter posting (sensitive HITL)
  • fte-odoo — Odoo 19 ERP invoices/payments/financials (critical HITL)
  • fte-documents — Reports and CEO Briefing generation
• Circuit breaker pattern: per-service state machine (3 failures → 300s cooldown)
• Correlation IDs: corr-YYYYMMDD-HHMMSS-XXXX from watcher through execution
• CEO Briefing: weekly aggregation from Odoo + tasks + social + bottlenecks
• Health monitoring: Logs/health.json with real-time service states

• Cloud VM (Ubuntu 24.04 at 141.145.146.17): runs 24/7, detects events, drafts responses
• Local laptop: reviews, approves, executes real actions (email send, social post, payments)
• FTE_ROLE environment variable: cloud (draft-only) vs local (full execution)
• Git-based vault sync: 60-second pull/commit/push cycle via src/git_sync.py
• Claim-by-move concurrency: atomic os.rename() prevents duplicate processing
• Single-writer dashboard: cloud writes to Updates/, local merges into Dashboard.md
• Secrets isolation: .gitignore + pre-commit hook + cloud-side audit (3 layers)
• Correlation ID propagation: corr-YYYY-MM-DD-XXXXXXXX traces full lifecycle across agents
• Stale detection: flags Pending_Approval >48h, Rejected >7d
• PM2 daemon management: 4 services (git-sync, gmail-watcher, scheduler, orchestrator)
• Live demo verified: real email detected → drafted → approved → sent via Gmail API

• Python 3.13+ with venv
• Claude Code
• Obsidian v1.11.x+ (optional, for vault viewing)

pip install watchdog pyyaml apscheduler mcp tweepy
pip install google-api-python-client google-auth-oauthlib  # Gmail
pip install playwright && playwright install chromium       # WhatsApp
pip install odoorpc                                        # Odoo ERP

# 1. Initialize vault
python src/setup_vault.py

# 2. Start file watcher
python src/file_drop_watcher.py

# 3. Drop a file and process
cp document.pdf ~/Desktop/DropForAI/
claude "check and process needs action"

# 4. Start Gmail watcher (requires credentials.json)
python .claude/skills/gmail-watcher/scripts/gmail_poll.py

# 5. Start scheduler daemon
python .claude/skills/daily-scheduler/scripts/scheduler_daemon.py

# 6. Run central orchestrator
python .claude/skills/central-orchestrator/scripts/orchestrator.py

# 7. Generate CEO briefing
claude "generate CEO briefing"

Registered in .claude/settings.json. All default to DRY_RUN=true.

fte/
├── src/
│   ├── vault_helpers.py           # Shared utilities
│   ├── setup_vault.py             # Vault initialization
│   ├── file_drop_watcher.py       # Filesystem watcher
│   ├── correlation.py             # Correlation ID generation
│   ├── circuit_breaker.py         # Circuit breaker state machine
│   ├── role_gate.py               # FTE_ROLE detection and enforcement
│   ├── claim_move.py              # Claim-by-move concurrency control
│   ├── git_sync.py                # Git-based vault sync service
│   ├── dashboard_merger.py        # Single-writer dashboard updates
│   ├── approval_watcher.py        # Local approval → execution pipeline
│   ├── rejection_handler.py       # Rejected draft escalation
│   ├── stale_detector.py          # Stale file detection
│   └── mcp/
│       ├── base_server.py         # Shared MCP server utilities
│       ├── email_server.py        # Email MCP server
│       ├── social_server.py       # Social media MCP server
│       ├── odoo_server.py         # Odoo ERP MCP server
│       └── documents_server.py    # Documents/Briefing MCP server
├── config/
│   ├── mcp-servers.json           # MCP server registry
│   ├── social-platforms.json      # Platform character limits
│   ├── schedules.json             # Scheduled task definitions
│   ├── actions.json               # Action registry
│   ├── ecosystem.config.js        # PM2 configuration (local)
│   ├── ecosystem.cloud.config.js  # PM2 configuration (cloud VM)
│   └── cloud-start.sh             # Cloud env wrapper for PM2 v6
├── .claude/
│   ├── settings.json              # MCP server registration
│   └── skills/                    # 12 Claude Code skills
│       ├── vault-interact/
│       ├── process-needs-action/
│       ├── check-and-process-needs-action/
│       ├── central-orchestrator/
│       ├── action-executor/
│       ├── gmail-watcher/
│       ├── whatsapp-watcher/
│       ├── daily-scheduler/
│       ├── ralph-retry/
│       ├── social-media-poster/
│       ├── odoo-connector/
│       ├── ceo-briefing/
│       └── health-monitor/
├── docs/
│   ├── how-to-use-ai-employee.md  # Usage guide for all 7 capabilities
│   ├── ai-employee-pitch.md       # Interview & presentation pitch
│   ├── architecture.md            # System architecture
│   ├── lessons-learned.md         # Development insights
│   └── demo-script.md             # 5-10 min demo walkthrough
├── pictures/                       # AI-generated visuals for social media
├── tests/
│   ├── unit/                      # Unit tests
│   └── manual/                    # Manual test plans
└── specs/                         # Feature specifications

# On cloud VM (Ubuntu 24.04):
git clone git@github.com:safdarayubpk/PersonalAIEmployee.git ~/AI_Employee_Vault
python3 -m venv ~/fte-env
source ~/fte-env/bin/activate
pip install watchdog pyyaml apscheduler google-api-python-client google-auth-oauthlib

# Transfer Gmail token from local (read-only OAuth token):
# On local: scp token.json ubuntu@<VM_IP>:~/AI_Employee_Vault/

# Create .env (never synced via git):
cat > ~/AI_Employee_Vault/.env << 'EOF'
FTE_ROLE=cloud
VAULT_PATH=/home/ubuntu/AI_Employee_Vault
DRY_RUN=true
EOF

# Start PM2 services:
pm2 start config/ecosystem.cloud.config.js
pm2 startup systemd -u ubuntu --hp /home/ubuntu
pm2 save

Verified 2026-03-12 with correlation ID corr-2026-03-12-d16b3470:

• Gmail: Create OAuth2 credentials in Google Cloud Console, save credentials.json in project root
• WhatsApp: First run requires QR code scan in browser
• Facebook/Instagram: Page Access Token via Meta Developer Portal
• Twitter/X: API keys via Twitter Developer Portal (OAuth 1.0a)
• Odoo: Self-hosted Odoo 19 Community, set ODOO_DB, ODOO_USER, ODOO_PASSWORD env vars

• How to Use — Quick reference for all 7 capabilities (START HERE)
• Pitch & Presentation — Elevator pitch, interview pitch, architecture overview
• User Guide — Complete setup and usage guide for beginners
• Architecture — System diagrams and component descriptions
• Lessons Learned — Development insights across tiers
• Demo Script — 5-10 minute demo walkthrough
• Gold Tier Test Plan — Manual test checklists
• Platinum Quickstart — Cloud VM setup and demo guide
• ADRs — 21 Architecture Decision Records (Bronze through Platinum)