个人AI员工自动化服务

Personal AI Employee — Silver Tier

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

Tier: Silver | Built with Claude Code + Obsidian + Python + Node.js MCP

A Digital FTE (Full-Time Equivalent) AI agent that autonomously manages email, WhatsApp, LinkedIn, and business tasks — 24/7, with human approval for all sensitive actions.

Architecture

A closed loop: the system perceives external events, remembers them as markdown, reasons over them with Claude, asks a human before anything sensitive, acts through MCP servers, and records every step back into memory.

flowchart TB
    S["Gmail · WhatsApp · LinkedIn · Filesystem"]
    W["Perception Layer — 4 Python Watchers<br/><i>base_watcher.py: polling · dedupe</i>"]
    V["Memory — Obsidian Vault<br/><i>markdown + frontmatter</i><br/>Tasks · Plans · Handbook · Accounting"]
    O["orchestrator.py<br/><i>dispatch · HITL routing · watchdog</i>"]
    C["Claude Code + 7 Agent Skills<br/><i>reason → plan → act</i>"]
    G{"Human Approval Gate<br/>sensitive actions only"}
    M["Action Layer — 2 MCP Servers<br/>email · linkedin"]
    D["Web Dashboard<br/><i>localhost:8765</i>"]

    S --> W --> V --> O --> C
    C --> G
    G -->|approved| M
    G -->|rejected| V
    M --> V
    V --> D

    classDef src fill:#0d1117,stroke:#2f81f7,color:#c9d1d9
    classDef mem fill:#0d1117,stroke:#8957e6,color:#c9d1d9
    classDef gate fill:#0d1117,stroke:#d29922,color:#f0d58a,stroke-width:2px
    classDef act fill:#0d1117,stroke:#3fb950,color:#c9d1d9
    classDef obs fill:#0d1117,stroke:#6e7681,color:#c9d1d9

    class S,W src
    class V,O,C mem
    class G gate
    class M act
    class D obs

The loop that matters: nothing reaches the outside world without passing the approval gate, and every action that does pass is written back into the vault. The agent's memory and its audit trail are the same artifact — which is why you can read what it did in plain markdown, and why a rejected action teaches it just as much as an approved one.

Gold Tier adds three more watchers, three more MCP servers (Twitter/X, Facebook, Odoo ERP), 90-day audit logging and exponential-backoff error recovery — SirHamza/gold-tier.

What It Looks Like Running

The dashboard reads the Obsidian vault directly. Every number above comes from markdown files on disk — there is no database and no hidden state, which is what makes the agent's memory auditable by hand.

Reproduce this in under a minute — see Quick Start. Screenshots use sample data from demo/seed_demo.py; no credentials involved.

Quick Start

Three levels. Level 0 needs nothing but Python and takes under a minute.

Level 0 — Demo mode (no credentials, no cost)

git clone https://github.com/SirHamza/silver-tier-complete.git && cd silver-tier-complete
pip install python-dotenv

python demo/seed_demo.py       # sample vault data, clearly marked
python dashboard/server.py     # http://localhost:8765

Nothing here touches a network service or needs an API key. Remove the sample data with python demo/seed_demo.py --clean.

Level 1 — Check what you have

python scripts/check_setup.py

Reports which runtimes, packages and credential groups are present. It never prints a secret value, only whether one is set.

Level 2 — Live mode

pip install -r requirements.txt
(cd mcp_servers/email_mcp && npm install)
(cd mcp_servers/linkedin_mcp && npm install)
cp .env.example .env

Two variables matter before anything else:

# Absolute path to this clone. Both MCP servers resolve their entry points
# from it, so nothing starts until this is correct.
AI_EMPLOYEE_ROOT=/absolute/path/to/silver-tier-complete

# Safety switch. While true, every outbound action is logged but NOT sent.
# Leave it on until you have watched a full cycle in the dashboard.
DRY_RUN=true

Everything else is optional and independent — an unconfigured watcher stays idle rather than failing, so you can start with Gmail alone.

pm2 start scheduling/pm2.config.js && pm2 save     # supervised
# or by hand:
python orchestrator/orchestrator.py
python watchers/gmail_watcher.py
python dashboard/server.py

Agent skills

claude /process-inbox                   # triage everything in Needs_Action
claude /ceo-briefing                    # morning business briefing
claude /send-email                      # dispatch an approved email
claude /post-linkedin "Your post text"
claude /create-plan "Task description"
claude /weekly-audit
claude /ralph-loop "<task>" --completion-promise "DONE" --max-iterations 10

Scheduled tasks (Windows)

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
.\scheduling\setup_windows_scheduler.ps1

The script resolves the project root from its own location, so it works wherever you cloned the repo. macOS and Linux use scheduling/setup_cron.sh.

Tests

pip install -r requirements-dev.txt
python -m pytest

11 tests covering watchers/base_watcher.py — the class all four watchers inherit from: the abstract contract, that Needs_Action is always created, and that a failing poll never kills the loop. A watcher that dies silently is worse than one that never started, because the operator believes it is still running.

Design Decisions

Four choices shaped this system. Each one bought something and cost something.

1 · The filesystem is the state machine

Chosen: a task is a markdown file, and its state is which folder it sits in — Needs_Action -> In_Progress -> Pending_Approval -> Approved / Rejected -> Done.

Given up: transactions, queries, concurrent writers, a schema.

Why: it makes the approval gate mv. Approving an action is moving a file, which works in Obsidian, in Finder, over SSH, or on a phone with a synced folder. No custom approval UI has to exist, and none can break. The dashboard is a reader of that state, not its owner — delete the dashboard and the system still works.

The cost is real: two watchers writing the same task at once would race. At single-operator scale that trade is worth it; at team scale it would not be.

2 · Approval is a gate, not a notification

Chosen: sensitive actions stop at Pending_Approval and stay there. The orchestrator only dispatches out of Approved.

Given up: speed. The agent cannot finish an email at 3 AM; it can only prepare one.

Why: an agent holding your Gmail token and your LinkedIn account is a liability surface, not just a productivity tool. The failure mode of "notify the human afterwards" is an apology to a client. The failure mode of "wait for the human" is a delay. Delays are recoverable.

DRY_RUN defaults to true in orchestrator.py and independently inside both MCP servers, so a bug in the orchestrator still cannot cause a real send. CI asserts every server keeps its guard.

3 · Actions go through MCP servers, not inline API calls

Chosen: each integration is a separate Node process speaking MCP.

Given up: simplicity and latency — two npm installs and a subprocess hop that an inline requests.post() would not need.

Why: credential isolation. The LinkedIn server only ever receives LinkedIn credentials. Each server is testable alone, replaceable alone, and usable by Claude Code directly without the orchestrator running at all.

4 · Watchers poll; they do not receive webhooks

Chosen: each of the four watchers polls on an interval via base_watcher.py.

Given up: latency — a 30-second poll averages 15 seconds behind a webhook.

Why: webhooks need a public endpoint, a domain, TLS and an inbound hole in the network. This runs on the operator's own machine with no inbound connectivity at all. Polling is the price of that, and 15 seconds is not a meaningful delay for triaging an inbox.

Project Structure

AI_Employe/
├── AI_Employee_Vault/           # Obsidian vault (GUI + long-term memory)
│   ├── Dashboard.md             # Real-time status (Obsidian view)
│   ├── Company_Handbook.md      # AI rules of engagement
│   ├── Business_Goals.md        # KPIs and revenue targets
│   ├── Needs_Action/            # Items from watchers awaiting Claude
│   ├── Plans/                   # PLAN_*.md files (Claude reasoning)
│   ├── Pending_Approval/        # Actions awaiting your approval
│   ├── Approved/                # Move files here to authorize
│   ├── Rejected/                # Move files here to cancel
│   ├── Done/                    # Completed task archive
│   ├── Logs/                    # JSON audit trail
│   ├── Briefings/               # Monday CEO briefings
│   ├── Content_Queue/           # LinkedIn post drafts
│   └── Accounting/              # Financial data
├── watchers/                    # Python perception scripts
│   ├── base_watcher.py          # Abstract base class
│   ├── gmail_watcher.py         # Gmail API → Needs_Action
│   ├── whatsapp_watcher.py      # Playwright WhatsApp Web → Needs_Action
│   ├── linkedin_watcher.py      # LinkedIn API + post-mode
│   └── filesystem_watcher.py   # Local file drops → Needs_Action
├── orchestrator/                # Master process
│   ├── orchestrator.py          # Folder watcher + MCP dispatcher
│   └── watchdog.py              # Process health monitor
├── mcp_servers/                 # External action servers
│   ├── email_mcp/               # Gmail OAuth2 (send, draft, list)
│   └── linkedin_mcp/            # LinkedIn REST API (post, feed, notifs)
├── dashboard/                   # Web Dashboard UI ← NEW
│   ├── server.py                # Python HTTP server + JSON API
│   └── index.html               # Real-time web dashboard
├── skills/                      # Agent Skill descriptors
│   ├── process-inbox.md
│   ├── ceo-briefing.md
│   ├── post-linkedin.md
│   ├── send-email.md
│   ├── create-plan.md
│   ├── weekly-audit.md
│   └── ralph-loop.md
├── .claude/commands/            # Claude Code slash commands
│   ├── process-inbox.md
│   ├── ceo-briefing.md
│   ├── post-linkedin.md
│   ├── send-email.md
│   ├── create-plan.md
│   ├── weekly-audit.md
│   └── ralph-loop.md
├── scheduling/
│   ├── pm2.config.js            # PM2 process management (all 6 processes)
│   └── setup_windows_scheduler.ps1  # Windows Task Scheduler
├── credentials/                 # Gmail credentials (gitignored)
├── sessions/                    # WhatsApp session data (gitignored)
├── .mcp.json                    # MCP server registration
├── .env                         # Credentials (gitignored)
├── .env.example                 # Template
├── requirements.txt
└── PLAN.md                      # Development roadmap

What's Included

Human-in-the-Loop (HITL) Workflow

1. Claude reads Needs_Action file
2. Claude creates: Pending_Approval/APPROVAL_*.md
3. You review the approval file in Obsidian or Dashboard UI
4. Move to /Approved  → Orchestrator dispatches action via MCP
   Move to /Rejected  → Action cancelled, logged

Actions that ALWAYS require approval:

• Sending emails to new contacts
• LinkedIn posts
• Any payment > $50

Security

Where This Sits

Four capability tiers, built in order. Each one is a working system on its own, not a stage of an unfinished one.

Silver is the smaller surface: the same architecture, the same approval gate, and the same markdown-as-memory model, with four integrations instead of seven. Start here if you want to understand the design; move to Gold to see how it holds under load.

Author

Hamza Saifuddin — AI Architect · Agentic Systems · Karachi, PK

Portfolio · GitHub · LinkedIn · hamzasaifuddinh@gmail.com

Licensed under MIT — use it, fork it, build on it.