Personal AI Employee

Local-first, human-in-the-loop autonomous agent. It watches your inbox and business signals, drafts the response, and waits for you to approve it before anything real happens.

What this is

Most "AI agent" products are a black box: you give a SaaS tool your credentials and hope it does the right thing. This project takes the opposite approach — every piece of state the agent knows or plans is a plain Markdown file you can read, edit, or delete yourself, and nothing irreversible (sending an email, posting socially, moving money) happens without you physically approving the draft first.

It runs entirely on your own machine, uses a local OpenCode agent for reasoning, and keeps its entire memory in an Obsidian vault.

Core Architecture

The system follows a Perception → Reasoning → Action loop.

graph TD
    subgraph "Perception (Watchers)"
        GW[Gmail Watcher] --> |Creates EMAIL.md| Inbox[(Vault / Needs_Action)]
        LW[LinkedIn Watcher] --> |Creates LEAD.md| Inbox
        FW[Filesystem Watcher] --> |Drops FILES.md| Inbox
    end

    subgraph "Reasoning (The Brain & Memory)"
        Inbox --> |Read Trigger| OC[OpenCode Engine]
        OC <--> |Uses Skills| Skills[Agent Skills]
        OC <--> |Checks Rules| CH[Company_Handbook.md]
        OC <--> |Checks Goals| BG[Business_Goals.md]
    end

    subgraph "Action (MCP Servers & HITL)"
        OC --> |Drafts Action| PA[(Vault / Pending_Approval)]
        PA --> |Human Reviews & Moves| APP[(Vault / Approved)]
        APP --> |Triggers| AW[Approval Watcher]
        AW --> |Executes via| MCP[MCP Servers]
        MCP --> |Logs to| Done[(Vault / Done & Logs)]
    end

1. The Senses (Watchers)

Lightweight Python background scripts (/watchers/) acting as the system's eyes and ears. Managed by orchestrator.py, they scan APIs and filesystems, transforming external events into Markdown files dropped into the Obsidian Vault.

2. The Brain & Memory

• The Brain: OpenCode runs in a continuous loop. Woken by new files in Needs_Action, it leverages custom Agent Skills (.agents/skills/) to break down complex tasks and draft solutions.
• The Memory: The Obsidian Vault (/vault/) acts as the state machine, config layer, and audit log. Everything the AI knows or plans is visible as local, editable text.

3. The Hands (MCP & HITL)

• Model Context Protocol (MCP): Standardized servers (/mcp_servers/) that expose external tools (like sending Gmail, posting socially, accessing Odoo) to OpenCode. See Project Status — not all of these are wired up or safe to use yet.
• Human-In-The-Loop (HITL): The AI writes draft actions to /Pending_Approval. Actions strictly wait for a human to drag the file to /Approved before the approval_watcher executes them.

Project Status

Being upfront about what actually works vs. what's scaffolding, so you don't wire something up expecting it to be production-ready:

Codebase & Vault Structure

/personal-ai-employee
├── .env                        # Environment Secrets (DO NOT COMMIT)
├── opencode.json               # OpenCode config: model, MCP servers, permissions
├── orchestrator.py             # Main entry point: Runs all background watchers continuously
├── vault/                      # 🧠 The Obsidian Vault (System State & Memory)
│   ├── Inbox/                  # Raw drops
│   ├── Needs_Action/           # Tasks awaiting OpenCode's attention
│   ├── Pending_Approval/       # OpenCode's drafted tasks awaiting human approval
│   ├── Approved/               # Human-approved tasks waiting for execution watcher
│   ├── Done/ & Logs/           # History of completed actions
│   ├── Company_Handbook.md     # Rules of behavior for the AI
│   ├── Business_Goals.md       # KPIs and targets for autonomous audits
│   └── Dashboard.md            # Real-time state overview
├── watchers/                   # 👀 The Senses — active Python background scripts
│   ├── gmail_watcher.py        # Monitors unread priority emails (multi-account via GMAIL_ACCOUNT_LABEL)
│   ├── linkedin_watcher.py     # Monitors LinkedIn connections/messages
│   ├── filesystem_watcher.py   # Event-driven local file ingester
│   ├── approval_watcher.py     # Executes tasks dropped in /Approved
│   ├── telegram_approval_watcher.py  # Pending_Approval → Telegram Approve/Reject/Edit ping
│   └── discord_approval_watcher.py   # Pending_Approval → Discord Approve/Reject/Edit ping
├── .agents/skills/             # 🛠️ OpenCode's Reasoning capabilities
│   ├── hitl-workflow/          # Logic for requesting human permissions
│   ├── email-skill/            # Logic for drafting, triaging emails
│   ├── linkedin-skill/         # Logic for B2B lead generation & posting
│   ├── ceo-briefing/           # Logic for weekly audits
│   ├── odoo-accounting/        # Logic for ERP connections
│   ├── social-manager/         # Logic for social media PR
│   ├── reasoning-loop/         # Deep multi-step task planning
│   └── ...
└── mcp_servers/                # 👐 The Hands
    ├── email/                  # Python MCP Server for Gmail
    ├── odoo_mcp.py             # Python MCP Server for local Odoo APIs (unwired, unsafe — see status table)
    └── socials_mcp.py          # Python MCP Server for FB/IG/Twitter (stub — see status table)

Setup & Installation

Prerequisites

1. Python 3.11+
2. OpenCode installed (npm install -g opencode-ai)
3. Obsidian (optional, for viewing the /vault visually)

Step-by-Step

1. Clone & install dependencies

   git clone https://github.com/AbdulSamad94/Personal-AI-Employee.git
   cd Personal-AI-Employee
   uv sync
   

2. Configure environment variables
   Create a .env file at the root (already gitignored):

   # Gmail watcher & MCP
   [email protected]
   GMAIL_APP_PASSWORD=your_16_digit_app_password
   
   # LinkedIn watcher integration
   LINKEDIN_TOKEN=your_oauth2_token
   LINKEDIN_PERSON_ID=your_id
   
   # Master safety switch — keep true until you've reviewed what the agent does
   DRY_RUN=true
   

3. Initialize the orchestrator
   Boots all background watchers. Leave it running in a terminal.

   python orchestrator.py
   

4. Boot up OpenCode
   In a second terminal:

   opencode
   > "Trigger the process-tasks skill to empty the Needs_Action folder."
   

   Or run it non-interactively (what the scheduled task does):

   opencode run "Process all pending tasks in vault/Needs_Action/..." --auto
   

Application Workflows

Secure Email Triage (Human-In-The-Loop)

sequenceDiagram
    participant Web as Gmail servers
    participant GW as gmail_watcher.py
    participant V as Vault (Obsidian)
    participant Q as OpenCode
    participant AW as approval_watcher.py
    participant MCP as MCP Email Server

    Web->>GW: New urgent client email arrives
    GW->>V: Creates EMAIL_101.md in /Needs_Action
    Q->>V: Detects EMAIL_101.md
    Q->>Q: Uses email-skill & hitl-workflow to plan reply
    Q->>V: Drafts response & moves to /Pending_Approval
    Note over V: Waiting for local human review...
    Human->>V: Drags via Obsidian into /Approved
    AW->>V: Detects approved file
    AW->>MCP: Sends JSON-RPC payload to dispatch
    MCP->>Web: Sends actual Email
    AW->>V: Moves EMAIL_101.md to /Done & Updates /Logs

Automated LinkedIn Lead Generation

sequenceDiagram
    participant LW as linkedin_watcher.py
    participant V as Vault (Obsidian)
    participant Q as OpenCode

    LW->>V: Scrapes daily metrics & new connections
    LW->>V: Logs to /Needs_Action/LINKEDIN_Event.md
    Q->>V: Analyzes connection profiles
    Q->>Q: Compares against Business_Goals.md
    Q->>V: Drafts personalized welcome DMs or Lead scores
    Q->>V: Places recommendations in /Pending_Approval

Security & Privacy Posture

• Zero-cloud memory: all internal state lives in local Markdown files inside /vault. You own the data.
• HITL by default: the AI uses the /Pending_Approval workflow. No irreversible API calls (payments, outgoing emails, social posts) trigger without an explicit, manual file move — this is enforced in approval_watcher.py, not just a policy statement.
• Dry-run sandbox: set DRY_RUN=true in .env to log intended actions without actually sending/posting anything, useful while testing changes.
• Known gap: the Odoo MCP server has no code-level dry-run/approval check (see Project Status) — don't wire it into opencode.json for real financial data until that's fixed.

Permission Policy

The intended action thresholds, as defined in vault/Company_Handbook.md. Today these are enforced through the Handbook + skill instructions the agent reads before acting, not hard-coded checks — treat this as policy the agent is instructed to follow, not a guarantee:

The "Ralph Wiggum" Retry Loop

scripts/ralph_loop.ps1 keeps OpenCode working a single task until it's actually moved to vault/Done/, instead of accepting the first response as complete — this fights the "lazy agent" problem where a model claims a task is done without doing it.

sequenceDiagram
    participant O as Orchestrator
    participant Q as OpenCode
    participant V as Vault (Obsidian)

    O->>V: Detects new file in /Needs_Action
    O->>Q: Bootstraps OpenCode with "Process Inbox" goal
    loop Ralph Wiggum retry loop
        Q->>V: Reads Tasks & Plans
        Q->>V: Executes step (e.g., Drafts email)
        Q->>Q: Checks completion criteria
        alt Task Not Found in /Done
            Q->>Q: Self-corrects & Loops
        else Task Moved to /Done
            Q->>O: Emits <promise>TASK_COMPLETE</promise>
        end
    end
    O->>O: Graceful Shutdown or Sleeps

Error Handling — current vs. planned

What's actually implemented today: orchestrator.py acts as a watchdog process, monitoring the PIDs of all watchers and auto-restarting any that exit with a non-zero code. Watchers catch and log exceptions broadly to stay alive across transient failures.

Not yet implemented (roadmap, not current behavior): exponential backoff on retried API calls, and automatic quarantine of a task into an ALERT_HUMAN.md file after repeated failures. If you build these, they'd slot naturally into the watcher poll loops and approval_watcher.py.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md for dev setup, where things live, and a list of good first contributions (the Odoo safety gate is the highest-value one). Licensed under MIT — see LICENSE.