Personal AI Employee Hackathon Vault

Building Autonomous Digital FTEs (2026) Your life and business on autopilot. Local-first, agent-driven, human-in-the-loop.

Target Tier

Platinum Tier (Always-On Cloud + Local Executive) Includes all requirements from Bronze, Silver, and Gold Tiers.

Features & Capabilities

1. Perception Layer (Watchers)
   • filesystem_watcher.py: Monitors drop folders locally and adds to /Needs_Action.
   • gmail_watcher.py: Fetches unread emails (with mock support if credentials absent).
   • whatsapp_watcher.py: Playwright-based watcher monitoring urgent WhatsApp messages.
2. Action Layer (MCP & Skills)
   • High-Professional Global AI Chatbot UI (with voice input capabilities, responsive glassmorphism, and accessibility compliance).
   • Odoo Community JSON-RPC via odoo-mcp/index.js (gets/creates invoices & journal entries).
   • Email MCP via email-mcp/index.js (Mocked for safety).
   • LinkedIn Poster (linkedin_poster.py) for automated social media.
   • Example Agent Skill defined in /skills/invoice-validation/SKILL.md.
3. Orchestration & Persistence Layer
   • watchdog_pm.py: Resilient System Process Manager keeping everything online.
   • orchestrator.py: Python-based task manager bridging Watchers -> Claude Reasoning -> MCP execution.
   • ralph_loop.sh: Bash script forcing continuous Claude execution until the queue is clear.
   • ceo_audit.py: Generates the exact "Monday Morning CEO Briefing".
   • vault_sync.sh: Git-based chronological sync script allowing an "Always-On" Cloud VM to share Obsidian vault state with the Local machine seamlessly.

Setup Instructions

1. Clone and Install

git clone https://github.com/kAmmarah/Hackathon-0.git
cd Hackathon-0

2. Backend Setup (Python Watchers & Orchestrator)

cd ai_engine
# Uses UV. 
uv sync # To install watchdog, google-auth, playwright, etc.
uv run playwright install chromium

3. Node Servers (MCP)

cd mcp-servers/odoo-mcp
npm install

4. Running the System To bring the AI Employee "online", start the System Watchdog process manager from the ai_engine directory:

cd ai_engine
uv run python watchdog_pm.py

This will spin up all file watchers, email watchers, orchestrators, and the Odoo MCP server concurrently.

Architecture Overview

This application enforces a Perception -> Reasoning -> Action architecture using the File System as its core database (local-first Obsidian structure).

• Perception: Background daemon scripts (watchers/) pipe signals into /AI_Employee_Vault/Needs_Action.
• Reasoning: Claude Code (The Orchestrator logic) reads tasks, produces reasoning chains via Agent Skills (/skills/*), and delegates high-risk tasks to /Pending_Approval.
• Action: The User moves files to /Approved, triggering the orchestrator to call explicit MCPs (like email-mcp or odoo-mcp).

See /AI_Employee_Vault/Dashboard.md for runtime status and /AI_Employee_Vault/Company_Handbook.md for Rules of Engagement.

Security Disclosure

• Credential Management: No tokens or passwords are hardcoded. System components look for .env or credentials.json files. These files are STRICTLY ignored by git via .gitignore.
• Sandboxing: API interaction is gated by human-in-the-loop (HITL). Claude lacks the ability to execute an action directly; it explicitly creates an approval request.
• Audit Logs: The system natively generates actionable audits (ceo_audit.py) and standard .json logs will track all MCP invocations.

Lessons Learned & Future Work

• Process Management is Hard: Transitioning isolated Python scripts into robust daemons necessitated building a custom PM (watchdog_pm.py) to prevent silent failures over night.
• State via Text: Using Obsidian Markdown files for pure application state works incredibly well but introduces file-locking collisions when both Cloud watcher and Local reasoning engine attempt to alter state simultaneously. The Platinum "Git Sync" approach with /In_Progress claims solves this effectively.

Demo Video

(Link to Demo Video will be provided per submission guidelines)