Hackathon 0
Finally, Today I completed my Hackathon 0 with All Tiers..
Ask AI about Hackathon 0
Powered by Claude Β· Grounded in docs
I know everything about Hackathon 0. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
AI Employee Vault - Complete Hackathon 0 Project
Tagline: Your life and business on autopilot. Local-first, agent-driven, human-in-the-loop.
Tier Declaration: Platinum (Partial - Cloud deployment pending)
Last Updated: April 5, 2026
π Table of Contents
- Project Overview
- Architecture
- Prerequisites & Setup
- Bronze Tier - Foundation
- Silver Tier - Functional Assistant
- Gold Tier - Autonomous Employee
- Platinum Tier - Always-On + AI Features
- What's Missing
- Project Structure
- Troubleshooting
- Security
Project Overview
A Personal AI Employee that proactively manages your personal affairs (Gmail, WhatsApp) and business (Social Media, Payments, Tasks) 24/7. Built as a "Digital FTE" (Full-Time Equivalent) that works ~9,000 hours/year vs a human's 2,000, at 85-90% cost savings.
Key Features:
- Local-first: All data stays on your machine (Obsidian Markdown vault)
- Proactive: Watchers monitor Gmail, WhatsApp, LinkedIn, Twitter, Facebook 24/7
- Human-in-the-Loop: Approval workflow prevents AI accidents
- ML-Powered: Learns from your corrections over time
- LLM-Enhanced: Generates natural language posts/emails (OpenAI/Gemini)
- Web Dashboard: Monitor, approve, and manage everything from a browser
- Voice Interface: Hands-free operation via voice commands
Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β EXTERNAL SOURCES β
β Gmail β WhatsApp β LinkedIn β Twitter β Facebook β
ββββββ¬βββββββββββ¬βββββββββββ¬ββββββββββββ¬βββββββββββ¬βββββββββββββββ
β β β β β
βΌ βΌ βΌ βΌ βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PERCEPTION LAYER (Watchers) β
β gmail_watcher β whatsapp_watcher β linkedin_watcher β etc. β
ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββ
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β OBSIDIAN VAULT (Local) β
β /Needs_Action/ β /Plans/ β /Pending_Approval/ β /Approved/ β
β Dashboard.md β Company_Handbook.md β Business_Goals.md β
ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββ
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β REASONING LAYER β
β Claude Code + Ralph Wiggum Loop (multi-step autonomy) β
β ML Classifier (TF-IDF + Naive Bayes) β
β LLM Generator (OpenAI/Gemini + template fallback) β
ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββ
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ACTION LAYER β
β MCP Servers (Email) β Multi-Platform Publisher β HITL Handler β
β Auto-Scaler β A/B Testing β Predictive Analytics β Voice β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Prerequisites & Setup
Required Software
| Component | Version | Purpose |
|---|---|---|
| Python | 3.13+ | Watchers, skills, orchestration |
| Node.js | v24+ LTS | MCP servers |
| Obsidian | v1.10.6+ | Knowledge base & dashboard |
| Claude Code | Latest | Primary reasoning engine |
| Git | Latest | Version control |
Python Dependencies
cd AI_Employee_Vault
# Core dependencies
pip install watchdog playwright google-auth google-auth-oauthlib google-api-python-client
# ML/AI dependencies
pip install scikit-learn joblib
# Web dashboard
pip install flask
# Voice interface (optional)
pip install SpeechRecognition pyttsx3
# System monitoring (for auto-scaler)
pip install psutil
# Install Playwright browsers
playwright install
Node.js Dependencies
cd AI_Employee_Vault/mcp_servers/email-mcp
npm install
Google API Setup
- Go to Google Cloud Console
- Enable Gmail API
- Create OAuth 2.0 credentials
- Download
credentials.jsonβ place in project root - First run of Gmail watcher will open browser for OAuth authorization
Bronze Tier - Foundation
Status: β COMPLETE (6/6 requirements met)
What's Included
| Requirement | File | Status |
|---|---|---|
| Obsidian vault | .obsidian/ | β |
| Dashboard.md | Dashboard.md | β |
| Company_Handbook.md | Company_Handbook.md | β |
| One watcher | watchers/filesystem_watcher.py | β |
| Folder structure | /Inbox, /Needs_Actions, /Done | β |
| Agent Skills | Skills/*.md (9 skill definitions) | β |
How to Run
1. File System Watcher (monitors /Inbox for new files):
cd AI_Employee_Vault
python watchers/filesystem_watcher.py
2. Test it:
# Drop a file into Inbox
echo "Process this" > Inbox/test.txt
# Watcher copies it to Needs_Actions with metadata
ls Needs_Actions/FILE_test.txt
ls Needs_Actions/FILE_test.txt_metadata.md
How to Verify
-
Dashboard.mdexists and shows bank balance, pending messages, active tasks -
Company_Handbook.mdcontains your rules of engagement - Dropping a file in
Inbox/creates files inNeeds_Actions/ - Claude Code can read and write to the vault
Silver Tier - Functional Assistant
Status: β COMPLETE (6/6 requirements met)
What's Included
| Requirement | File | Status |
|---|---|---|
| 2+ watchers | 6 watchers total | β |
| LinkedIn auto-posting | Skills/auto_linkedin_poster.py | β |
| Plan.md files | Plans/ directory | β |
| MCP server | mcp_servers/email-mcp/index.js | β |
| HITL approval | Skills/hitl_approval_handler.py | β |
| Scheduling | schedulers/ (daily + weekly) | β |
Watchers
| Watcher | File | Interval | Keywords |
|---|---|---|---|
| File System | watchers/filesystem_watcher.py | Real-time | N/A |
| Gmail | watchers/gmail_watcher.py | 120s | urgent, invoice, payment, sales |
watchers/linkedin_watcher.py | 60s | sales, client, project | |
watchers/whatsapp_watcher.py | 30s | urgent, invoice, payment, sales | |
| Facebook/Instagram | watchers/facebook_instagram_watcher.py | 60s | sales, client, project |
watchers/twitter_watcher.py | 60s | sales, client, project |
How to Run
Start individual watchers:
cd AI_Employee_Vault
# Gmail Watcher (first run opens browser for OAuth)
python watchers/gmail_watcher.py
# LinkedIn Watcher (first run requires LinkedIn login)
python watchers/linkedin_watcher.py
# WhatsApp Watcher (first run requires QR code scan)
python watchers/whatsapp_watcher.py
# Auto LinkedIn Poster (creates drafts from business leads)
python Skills/auto_linkedin_poster.py
Start all watchers with PM2 (production):
npm install -g pm2
cd AI_Employee_Vault
pm2 start watchers/filesystem_watcher.py --name "fs_watcher" --interpreter python
pm2 start watchers/gmail_watcher.py --name "gmail_watcher" --interpreter python
pm2 start watchers/linkedin_watcher.py --name "linkedin_watcher" --interpreter python
pm2 start watchers/whatsapp_watcher.py --name "whatsapp_watcher" --interpreter python
pm2 start Skills/auto_linkedin_poster.py --name "linkedin_poster" --interpreter python --cron "*/5 * * * *"
pm2 save
pm2 startup
Start MCP Server:
cd AI_Employee_Vault/mcp_servers/email-mcp
node index.js
How to Test
- Gmail Watcher: Send yourself an email with "urgent" or "invoice" in subject, mark as unread, wait 120s
- LinkedIn Poster: Create a business lead in
Needs_Actions/, runpython Skills/auto_linkedin_poster.py, checkPending_Approval/ - HITL Workflow: Check
Pending_Approval/β move file toApproved/β HITL handler executes it - MCP Email: Use Claude Code to call
draft_emailtool, checkPlans/for draft
Gold Tier - Autonomous Employee
Status: β COMPLETE (7/8 - Odoo accounting pending)
What's Included
| Requirement | File | Status |
|---|---|---|
| Cross-domain integration | Skills/cross_domain_integrator.py | β |
| Facebook/Instagram | watchers/facebook_instagram_watcher.py | β |
| Twitter integration | watchers/twitter_watcher.py + Skills/twitter_post_generator.py | β |
| Weekly audit + CEO briefing | Skills/weekly_audit_briefer.py | β |
| Error recovery | utils/error_recovery.py | β |
| Audit logging | utils/audit_logger.py | β |
| Ralph Wiggum loop | tools/ralph_loop_runner.py | β |
| Odoo accounting (MCP) | NOT IMPLEMENTED | β |
How to Run
Cross Domain Integrator (classifies personal vs business, routes appropriately):
cd AI_Employee_Vault
python Skills/cross_domain_integrator.py
Ralph Wiggum Loop (multi-step autonomous task execution):
python tools/ralph_loop_runner.py "Process all files in Needs_Actions" --max-iterations 20
Weekly Audit Briefer (generates CEO briefing):
python Skills/weekly_audit_briefer.py
# Output: Briefings/ceo_briefing_YYYYMMDD.md
Error Recovery Tests:
python test_error_recovery.py
# Validates: bad input handling, error logging, error files, degradation plans, retry with backoff, graceful skip, audit logger
How to Test
- Cross-Domain: Drop files in
Needs_Actions/, run integrator, checkPending_Approval/(personal) andPlans/(business) - Ralph Loop: Run with test data, verify all 11 steps execute (scan β classify β route β summary β draft β approval β execute β publish β log β done)
- Weekly Audit: Run briefer, check
Briefings/for generated CEO report with revenue, bottlenecks, suggestions - Error Recovery: Disconnect network, run a watcher, verify exponential backoff retry in
Logs/error_*.log
Platinum Tier - Always-On + AI Features
Status: π PARTIALLY COMPLETE (Hackathon cloud requirements pending, AI features complete)
AI Features Included (Beyond Hackathon Spec)
| Feature | File | Status |
|---|---|---|
| Web Dashboard | dashboard/app.py + 8 templates | β |
| ML-Based Classification | utils/ml_classifier.py | β |
| LLM Content Generation | utils/llm_generator.py | β |
| Multi-Platform Publishing | Skills/multi_platform_publisher.py | β |
| Predictive Analytics | Skills/predictive_analytics.py | β |
| A/B Testing Framework | Skills/ab_testing_framework.py | β |
| Auto-Scaling | Skills/auto_scaler.py | β |
| Voice Interface | Skills/voice_interface.py | β |
Hackathon Platinum Requirements (Not Yet Implemented)
| Requirement | Status | Notes |
|---|---|---|
| Cloud deployment (24/7 VM) | β | Requires Oracle/AWS VM setup |
| Work-zone specialization | β | Cloud vs local routing logic |
| Synced vault (Git/Syncthing) | β | No git repo initialized |
| Claim-by-move rule | β | No multi-agent ownership mechanism |
| Odoo on cloud VM | β | Odoo not implemented (also Gold gap) |
| A2A upgrade | β | Agent-to-Agent protocol |
How to Run Platinum Features
1. Web Dashboard:
cd AI_Employee_Vault
python dashboard/app.py
# Open browser: http://localhost:5000
Dashboard pages:
/- Main dashboard with stats, charts, quick actions/queue- Needs Actions queue viewer/approvals- Approve/reject workflow UI/logs- Audit log viewer with filters/errors- Error reports viewer/briefings- CEO briefings viewer/ml- ML Classifier management (train, view data, retrain)/llm- LLM content generator (LinkedIn posts, emails, tweets, WhatsApp)
2. ML Classifier (replaces keyword matching with ML):
# Train from existing data
python utils/ml_classifier.py train --dirs Needs_Actions Done
# Classify a file
python utils/ml_classifier.py classify Needs_Actions/some_file.md
# View stats
python utils/ml_classifier.py stats
# Learn from a correction
python utils/ml_classifier.py learn Needs_Actions/some_file.md --domain business --source linkedin
3. LLM Content Generator:
# Generate LinkedIn post
python utils/llm_generator.py generate linkedin --lead "Client needs website, budget $5000" --tone professional
# Generate email response
python utils/llm_generator.py generate email --original "Need a quote for..." --type sales_reply --tone friendly
# Generate tweet
python utils/llm_generator.py generate tweet --topic "New product launch" --tone excited
# Check status
python utils/llm_generator.py status
4. Multi-Platform Publisher:
# Dry run (simulate publishing)
python Skills/multi_platform_publisher.py publish --dry-run
# Publish all approved files
python Skills/multi_platform_publisher.py publish --all
# Check status
python Skills/multi_platform_publisher.py status
# Configure platforms
python Skills/multi_platform_publisher.py config --platform twitter --enable
5. Predictive Analytics:
# Full analytics report
python Skills/predictive_analytics.py report
# Revenue forecast
python Skills/predictive_analytics.py forecast
# Detect anomalies
python Skills/predictive_analytics.py anomalies
# Score a lead
python Skills/predictive_analytics.py lead-score --content "Client needs website, budget $8000, 3 weeks timeline"
# View trends
python Skills/predictive_analytics.py trends --days 7
6. A/B Testing:
# Create a test
python Skills/ab_testing_framework.py create --name "LinkedIn Post Tone" --variants professional casual formal
# Record results
python Skills/ab_testing_framework.py record --test <test_id> --variant professional --score 85
# View all tests
python Skills/ab_testing_framework.py list
# Get winner
python Skills/ab_testing_framework.py winner --test <test_id>
# Get recommendations
python Skills/ab_testing_framework.py recommendations
7. Auto-Scaler:
# Check status
python Skills/auto_scaler.py status
# Evaluate and apply scaling
python Skills/auto_scaler.py evaluate
# Reset to defaults
python Skills/auto_scaler.py reset
8. Voice Interface:
# Interactive mode (text-based for testing)
python Skills/voice_interface.py cmd "status"
python Skills/voice_interface.py cmd "queue"
python Skills/voice_interface.py cmd "approve 1"
python Skills/voice_interface.py cmd "help"
# Full voice mode (requires microphone + SpeechRecognition package)
python Skills/voice_interface.py listen
Available voice commands: approve [number], reject [number], status, queue, how many pending, list approvals, help, exit
What's Missing
Critical Gaps
| Gap | Tier | Priority | Effort |
|---|---|---|---|
| Odoo Accounting via MCP | Gold | HIGH | 20-30 hours |
| Cloud Deployment | Platinum | MEDIUM | 10-15 hours |
| Synced Vault (Git) | Platinum | MEDIUM | 2-4 hours |
| Work-Zone Specialization | Platinum | LOW | 8-12 hours |
| Claim-by-Move Rule | Platinum | LOW | 4-6 hours |
| A2A Protocol | Platinum | LOW | 10-15 hours |
Odoo Accounting (Highest Priority Missing Feature)
To implement:
- Install Odoo Community Edition (self-hosted, local or cloud)
- Create MCP server using Odoo's JSON-RPC APIs
- Implement: invoice creation, payment drafting, transaction logging
- Integrate with HITL approval workflow
Reference: https://www.odoo.com/documentation/19.0/developer/reference/external_api.html
Project Structure
Hackathona 0/
βββ credentials.json # Google OAuth credentials
βββ package.json # Node.js dependencies
βββ README.md # This file
β
βββ AI_Employee_Vault/ # Main vault
βββ Dashboard.md # Real-time summary
βββ Company_Handbook.md # Rules of engagement
βββ Business_Goals.md # Q1/Annual goals tracking
βββ mcp.json # MCP server configuration
βββ SETUP_GUIDE.md # Detailed setup guide
βββ ERROR_RECOVERY_TEST_GUIDE.md # Error recovery testing guide
β
βββ watchers/ # Perception layer
β βββ filesystem_watcher.py # Bronze: File monitoring
β βββ gmail_watcher.py # Silver: Gmail monitoring
β βββ linkedin_watcher.py # Silver: LinkedIn monitoring
β βββ whatsapp_watcher.py # Silver: WhatsApp monitoring
β βββ facebook_instagram_watcher.py # Gold: Facebook/Instagram
β βββ twitter_watcher.py # Gold: Twitter monitoring
β
βββ Skills/ # Processing & action skills
β βββ cross_domain_integrator.py # Gold: Personal vs business routing
β βββ auto_linkedin_poster.py # Silver: LinkedIn post drafts
β βββ hitl_approval_handler.py # Silver: HITL workflow
β βββ social_summary_generator.py # Gold: Social message summaries
β βββ twitter_post_generator.py # Gold: Twitter post generation
β βββ weekly_audit_briefer.py # Gold: CEO briefing generation
β βββ multi_platform_publisher.py # Platinum: Multi-platform publishing
β βββ predictive_analytics.py # Platinum: Lead scoring, forecasting
β βββ ab_testing_framework.py # Platinum: A/B content testing
β βββ auto_scaler.py # Platinum: Dynamic load scaling
β βββ voice_interface.py # Platinum: Voice commands
β
βββ utils/ # Shared utilities
β βββ audit_logger.py # Gold: Centralized audit logging
β βββ error_recovery.py # Gold: Exponential backoff retry
β βββ ml_classifier.py # Platinum: ML-based classification
β βββ llm_generator.py # Platinum: LLM content generation
β
βββ dashboard/ # Platinum: Web dashboard
β βββ app.py # Flask server
β βββ requirements.txt # Flask dependencies
β βββ templates/ # HTML templates (8 files)
β
βββ mcp_servers/email-mcp/ # Silver: Email MCP server
β βββ index.js
β βββ package.json
β
βββ tools/ # Orchestration
β βββ ralph_loop_runner.py # Gold: Multi-step task execution
β βββ RALPH_LOOP_GUIDE.md
β
βββ schedulers/ # Scheduling scripts
β βββ daily_scheduler.ps1/.sh
β βββ weekly_audit_briefer.ps1/.sh
β
βββ ml_model/ # ML classifier data
β βββ classifier_model.pkl
β βββ training_data.json
β βββ metadata.json
β
βββ Inbox/ # Drop files here for processing
βββ Needs_Actions/ # Auto-processed items
βββ Plans/ # Draft content
βββ Pending_Approval/ # HITL queue
βββ Approved/ # Approved content
βββ Rejected/ # Rejected content
βββ Done/ # Completed tasks
βββ Logs/ # Audit & error logs
βββ Errors/ # Detailed error reports
βββ Briefings/ # CEO weekly briefings
βββ session/ # Browser sessions (LinkedIn, WhatsApp, etc.)
Troubleshooting
Common Issues
| Issue | Solution |
|---|---|
| Gmail "credentials.json not found" | Copy client secret to project root as credentials.json |
| Playwright "Browser not found" | Run playwright install |
| Watcher stops overnight | Use PM2: pm2 start watcher.py --interpreter python |
| Token expired (Gmail) | Delete watchers/token.json, re-run Gmail watcher |
| CSS selectors not working | Update selectors in watcher scripts (platforms change) |
| Permission denied | Run terminal as Administrator |
| Flask dashboard won't start | pip install flask |
| ML classifier not available | pip install scikit-learn joblib |
| Voice interface not working | pip install SpeechRecognition pyttsx3 |
Error Recovery
All watchers and skills include error recovery:
- Exponential backoff retry (1s β 2s β 4s, max 60s)
- Error logging to
/Logs/error_[component]_[date].log - Graceful degradation (skip bad input, continue processing)
- Manual action plans created after 10+ consecutive errors
Run tests: python test_error_recovery.py
Security
Credential Management
- NEVER commit
credentials.json,.env, or session files - Use environment variables for API keys
- Rotate credentials monthly
- Add
.gitignoreimmediately if initializing git repo
Human-in-the-Loop Rules
| Action | Auto-Approve Threshold | Always Requires Approval |
|---|---|---|
| Email replies | Known contacts | New contacts, bulk sends |
| Payments | < $50 recurring | All new payees, > $100 |
| Social media | Scheduled posts | Replies, DMs |
| File operations | Create, read | Delete, move outside vault |
Audit Trail
Every action is logged to /Logs/audit_YYYYMMDD.json with:
- Timestamp, actor, action type, target, parameters, result
- 90-day retention with auto-cleanup
Quick Reference
Start Everything (Development)
# Terminal 1: File System Watcher
python watchers/filesystem_watcher.py
# Terminal 2: Gmail Watcher
python watchers/gmail_watcher.py
# Terminal 3: LinkedIn Watcher
python watchers/linkedin_watcher.py
# Terminal 4: WhatsApp Watcher
python watchers/whatsapp_watcher.py
# Terminal 5: Web Dashboard
python dashboard/app.py
Start Everything (Production with PM2)
cd AI_Employee_Vault
pm2 start watchers/filesystem_watcher.py --name "fs_watcher" --interpreter python
pm2 start watchers/gmail_watcher.py --name "gmail_watcher" --interpreter python
pm2 start watchers/linkedin_watcher.py --name "linkedin_watcher" --interpreter python
pm2 start watchers/whatsapp_watcher.py --name "whatsapp_watcher" --interpreter python
pm2 start Skills/auto_linkedin_poster.py --name "linkedin_poster" --interpreter python --cron "*/5 * * * *"
pm2 start dashboard/app.py --name "dashboard" --interpreter python
pm2 save
pm2 startup
Check Status
pm2 status
pm2 logs
Version: 1.0
Tiers Complete: Bronze β
| Silver β
| Gold β
(7/8) | Platinum π (AI features complete, cloud deployment pending)
License: Internal Use Only
