Personal AI Employee

Hackathon 0: Building Autonomous FTEs (Full-Time Equivalents)

Your life and business on autopilot. Local-first, agent-driven, human-in-the-loop.

A Digital Full-Time Employee (FTE) powered by dual AI engines (Claude Code + OpenAI) and Obsidian vault that proactively manages personal and business affairs 24/7. Three watchers (File, Gmail, WhatsApp) detect incoming items, Claude reasons about them, and the HITL approval workflow keeps the human in control of sensitive actions.

Architecture

EXTERNAL SOURCES                    PERCEPTION LAYER (3 Watchers)
  Files in                            File Watcher (Python)
  /mnt/d/AI-Employee-Inbox   --->    monitors every 10s
                                            |
  Gmail (OAuth2)              --->    Gmail Watcher (Google API)
  texcot...@gmail.com                monitors every 2min
                                            |
  WhatsApp Web                --->    WhatsApp Watcher (Playwright)
  Business keyword scanning          monitors every 30s
                                            |
                                            v
                              OBSIDIAN VAULT (Local Markdown)
                              +-------------------------------+
                              | /Inbox       /Needs_Action    |
                              | /Pending_Approval  /Approved  |
                              | /Rejected    /Done            |
                              | /Briefings   /Logs            |
                              | Dashboard.md                  |
                              | Company_Handbook.md           |
                              | Business_Goals.md             |
                              +-------------------------------+
                                            |
                                            v
                              REASONING LAYER (Dual AI Engine)
                              Claude Code CLI -> vault checks
                              Claude API -> vault reasoning
                              OpenAI API -> chat companion
                              Follows Company_Handbook rules
                                            |
                              +-------------+-------------+
                              |                           |
                              v                           v
                        AUTO-EXECUTE              HITL APPROVAL
                        (Low risk)            (Sensitive actions)
                        Update dashboard      Create approval file
                        Categorize files      Wait for human decision
                        Log activities        Execute after approval
                                            |
                                            v
                              ACTION LAYER (Agent Skills + Backend)
                              4 Claude Code agent skills
                              FastAPI backend (dual AI)
                              CEO Briefing generator (data-driven)
                              Orchestrator (process management)
                              Cron scheduling (automated tasks)

Perception -> Reasoning -> Action Flow

Perception: 3 Watchers (File, Gmail, WhatsApp) detect new items from external sources
Reasoning: Claude Code reads vault, applies Company_Handbook rules, reasons about actions
Action: Auto-execute low-risk tasks, HITL-approve sensitive ones, update dashboard, generate briefings

Quick Start

Prerequisites

Python 3.11+
Node.js 18+ (for frontend)
Claude Code CLI (for orchestration)
Google Cloud OAuth credentials (for Gmail watcher)
Playwright + Chromium (for WhatsApp watcher)

Setup

# Clone and enter project
git clone https://github.com/asadullah48/hackathon-completion-engine.git
cd hackathon-completion-engine

# Install Python dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your API keys (ANTHROPIC_API_KEY + OPENAI_API_KEY)

# Create the drop folder (file watcher monitors this)
mkdir -p /mnt/d/AI-Employee-Inbox

Run Individual Watchers

# File Watcher -- monitors drop folder
python watchers/file_watcher.py --vault ./vault

# Gmail Watcher -- requires credentials.json + OAuth setup
python watchers/gmail_watcher.py --vault ./vault

# WhatsApp Watcher -- requires Playwright + QR code scan
pip install playwright && playwright install chromium
export DISPLAY=:0  # WSL2 with WSLg
python watchers/whatsapp_watcher.py --vault ./vault

Run the Orchestrator (Full Mode)

# All watchers + Claude Code + scheduling
python orchestrator.py --gmail --whatsapp

# File watcher only + Claude Code
python orchestrator.py

# Preview mode (no actual actions)
python orchestrator.py --dry-run

Run the Backend API

cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
# Visit http://localhost:8000/health
# Visit http://localhost:8000/api/vault/status

Run the Frontend

cd frontend
npm install && npm run dev
# Visit http://localhost:3000

Generate CEO Briefing

python watchers/ceo_briefing_generator.py --vault ./vault
# Output: vault/Briefings/YYYY-MM-DD-ceo-briefing.md

Setup Cron Jobs

bash scripts/setup-cron.sh
# Installs: Monday 9AM briefing, 5-min Gmail checks, 6-hour dashboard updates

Key Features

1. Three Watchers (Perception Layer)

Watcher	Source	Interval	Auth
File Watcher	`/mnt/d/AI-Employee-Inbox`	10s	None
Gmail Watcher	Gmail inbox (OAuth2)	2min	Google OAuth `credentials.json`
WhatsApp Watcher	WhatsApp Web (Playwright)	30s	QR code scan

Each watcher detects relevant items, creates structured action files in vault/Needs_Action/, and logs activity to vault/Logs/.

2. Dual AI Engine (Reasoning Layer)

Engine	Purpose	Integration
Claude Code CLI	Vault reasoning & orchestration	`claude --print` via orchestrator
Claude API	Vault item analysis & triage	`backend/services/claude_service.py`
OpenAI API	Chat companion with constitutional rules	`backend/services/chatgpt_service.py`

3. Human-in-the-Loop (HITL) Workflow

Sensitive actions create approval files in vault/Pending_Approval/. Move files to vault/Approved/ or vault/Rejected/ to make decisions. The AI never acts on sensitive matters without human approval.

Auto-Execute: Read/categorize files, update dashboard, log activities, generate briefings Requires Approval: External comms, payments >$50, production deploys, data deletion

4. Agent Skills (4 Claude Code Skills)

Specialized Claude Code agent skills in .claude/agents/fte/:

dashboard-updater -- Scans vault folders, updates Dashboard.md with real-time metrics
hitl-approval-manager -- Creates/processes approval requests, tracks decisions
ceo-briefing-generator -- Weekly executive briefings from real vault data
file-processor -- Categorizes and triages Inbox items by file type

5. CEO Briefing (Data-Driven)

Automated weekly briefing generated every Monday at 9 AM:

Reads real data from vault/Logs/ (last 7 days)
Counts items in all vault folders
Identifies bottlenecks (items >48 hours old)
Reports watcher health status
Provides actionable recommendations

6. Constitutional AI

Backend middleware enforces safety rules on chat endpoints. Blocked queries get Socratic responses. Flagged queries enter HITL review.

7. Orchestrator (Master Process)

orchestrator.py coordinates everything:

Starts/monitors/restarts crashed watchers
Triggers Claude Code vault checks on interval
Schedules CEO briefings (Monday 9 AM)
Graceful shutdown on SIGINT/SIGTERM

8. Backend API Endpoints

Endpoint	Method	Purpose
`/`	GET	Service info + AI engine status
`/health`	GET	Health check with dual engine config
`/api/chat`	POST	Chat with constitutional filtering
`/api/vault/status`	GET	Real-time vault folder counts
`/api/vault/triage`	GET	Claude-powered triage recommendations
`/api/vault/reason`	POST	Analyze specific vault items with Claude
`/api/vault/needs-action`	GET	List items awaiting action
`/api/conversations/{id}`	GET	Conversation history

Vault Structure

vault/
  Dashboard.md           # Real-time business snapshot (auto-updated)
  Company_Handbook.md    # Rules of engagement (v2.0.0)
  Business_Goals.md      # Strategic objectives and KPIs
  Inbox/                 # New items to triage
  Needs_Action/          # Items requiring processing
  Pending_Approval/      # HITL: awaiting human decision
  Approved/              # Human-approved actions
  Rejected/              # Human-rejected actions
  Done/                  # Completed items
  Briefings/             # CEO briefing output
  Logs/                  # Daily JSON activity logs
  Conversation_Logs/     # Chat history

Tech Stack

Layer	Technology
Reasoning	Claude Code CLI + Claude API (Anthropic)
Chat	OpenAI API + Constitutional AI middleware
Memory/GUI	Obsidian vault (local Markdown)
Perception	3 Python watchers (file, Gmail, WhatsApp)
Backend	Python FastAPI + Uvicorn
Frontend	Next.js 16 + TypeScript + Tailwind CSS
Browser Automation	Playwright (WhatsApp Web)
Scheduling	Python `schedule` + cron
Orchestration	Python orchestrator with process management
Deployment	Render (backend) + Vercel (frontend)

Live Deployment

Service	URL
Backend API (Render)	https://personal-ai-employee-backend.onrender.com
Frontend (Vercel)	https://frontend-three-kappa-64.vercel.app

Quick Verify

# Health check (dual AI engines)
curl https://personal-ai-employee-backend.onrender.com/health

# Vault status (real-time folder counts)
curl https://personal-ai-employee-backend.onrender.com/api/vault/status

# Service info
curl https://personal-ai-employee-backend.onrender.com/

Deploy from Source

Render (Backend):

Push to GitHub
Connect repo to Render → auto-detects render.yaml
Set OPENAI_API_KEY and ANTHROPIC_API_KEY as env vars

Vercel (Frontend):

cd frontend
vercel --prod -e NEXT_PUBLIC_API_URL=https://personal-ai-employee-backend.onrender.com

Tier Compliance

Bronze Tier -- COMPLETE

Obsidian vault with Dashboard.md (real-time metrics)
Company_Handbook.md (v2.0.0 with decision framework)
One working Watcher script (file watcher)
Claude Code reading/writing vault (orchestrator + API)
Folder structure: /Inbox, /Needs_Action, /Done + 6 more
AI functionality as Agent Skills (4 skills)

Silver Tier -- COMPLETE

Three Watcher scripts (File + Gmail + WhatsApp)
Claude reasoning loop (orchestrator triggers claude --print)
HITL approval workflow (Pending_Approval folder-based)
Basic scheduling (cron + Python schedule)
Agent Skills with YAML frontmatter (executable format)

Gold Tier -- COMPLETE

CEO Briefing with real data (data-driven from vault/Logs)
Audit logging (JSON logs in vault/Logs/)
Dual AI engine (OpenAI chat + Claude reasoning)
Error recovery (orchestrator restarts crashed watchers)
Deployment ready (render.yaml + Vercel)

Hackathon Submission

Deliverable	Link / Status
GitHub Repository	asadullah48/hackathon-completion-engine
Live Backend	personal-ai-employee-backend.onrender.com
Live Frontend	frontend-three-kappa-64.vercel.app
Demo Video	TODO: Add YouTube/Loom link
Tier Declaration	Gold
Architecture	See diagram above
Security	Credentials in `.env` (gitignored); HITL for sensitive actions; audit logging

Author

Asadullah Shafique

GitHub: @asadullah48
GIAIC Roll: 00458550
Program: Panaversity Hackathon II

License

MIT License - See LICENSE file for details

Built as an Autonomous Digital FTE -- Your life and business on autopilot.

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
.claude		.claude
.github/workflows		.github/workflows
backend		backend
config		config
download		download
engine		engine
frontend		frontend
hackathons		hackathons
scripts		scripts
skills		skills
specs		specs
tests		tests
vault		vault
watchers		watchers
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CLAUDE.md		CLAUDE.md
COMPLETION_REPORT.md		COMPLETION_REPORT.md
CONSTITUTION-H0.md		CONSTITUTION-H0.md
CONSTITUTION.md		CONSTITUTION.md
DISCORD_INTEGRATION.md		DISCORD_INTEGRATION.md
GEMINI.md		GEMINI.md
IMPROVEMENTS_SUMMARY.md		IMPROVEMENTS_SUMMARY.md
KUBERNETES_IMPROVEMENTS.md		KUBERNETES_IMPROVEMENTS.md
LICENSE		LICENSE
PROJECT_CONSTITUTION.md		PROJECT_CONSTITUTION.md
PROJECT_STATISTICS.md		PROJECT_STATISTICS.md
PROMPTS.md		PROMPTS.md
QWEN.md		QWEN.md
README.md		README.md
ROADMAP.md		ROADMAP.md
SILVER_TIER_VALIDATION.md		SILVER_TIER_VALIDATION.md
SYSTEM_DIAGNOSTICS_REPORT.md		SYSTEM_DIAGNOSTICS_REPORT.md
backend-health-improvements.yaml		backend-health-improvements.yaml
demo.py		demo.py
discord_bot.py		discord_bot.py
discord_config.json		discord_config.json
discord_integration.py		discord_integration.py
frontend-health-improvements.yaml		frontend-health-improvements.yaml
monitoring-alerts.yaml		monitoring-alerts.yaml
notification-health-improvements.yaml		notification-health-improvements.yaml
notification-patch.yaml		notification-patch.yaml
notification-pdb.yaml		notification-pdb.yaml
notification-strategic-patch.yaml		notification-strategic-patch.yaml
orchestrator.py		orchestrator.py
pyproject.toml		pyproject.toml
render.yaml		render.yaml
requirements.txt		requirements.txt
setup_discord_env.sh		setup_discord_env.sh
setup_github.sh		setup_github.sh
start_server.sh		start_server.sh
test_backend_dapr_startup.py		test_backend_dapr_startup.py
test_dapr_integration.py		test_dapr_integration.py
test_discord_integration.py		test_discord_integration.py
test_implementation.py		test_implementation.py
webhook_server.py		webhook_server.py

Folders and files

Latest commit

History

Repository files navigation

Personal AI Employee

Architecture

Perception -> Reasoning -> Action Flow

Quick Start

Prerequisites

Setup

Run Individual Watchers

Run the Orchestrator (Full Mode)

Run the Backend API

Run the Frontend

Generate CEO Briefing

Setup Cron Jobs

Key Features

1. Three Watchers (Perception Layer)

2. Dual AI Engine (Reasoning Layer)

3. Human-in-the-Loop (HITL) Workflow

4. Agent Skills (4 Claude Code Skills)

5. CEO Briefing (Data-Driven)

6. Constitutional AI

7. Orchestrator (Master Process)

8. Backend API Endpoints

Vault Structure

Tech Stack

Live Deployment

Quick Verify

Deploy from Source

Tier Compliance

Bronze Tier -- COMPLETE

Silver Tier -- COMPLETE

Gold Tier -- COMPLETE

Hackathon Submission

Author

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages