EmployeeOS

An open source "Company Brain" that runs in your terminal. You tell it about your company once, hire some AI employees, and it keeps watching, learning, and planning — every hour, every day, every week — without you having to ask.

Not a chatbot. Not a task runner. Something between a Chief of Staff and an always-on analyst.

---

What actually happens

When you run employeeos start, three things happen in a loop:

Every hour — each AI employee you hired (Marketing, Sales, Support, Finance, HR) analyzes their domain using two parallel sub-agents: one that scans for problems, one that recommends the next action. If anything is worth doing, a plan is created and queued for your approval. Approved plans get executed, and the outcome gets recorded as a learning that feeds future decisions. New emails in your inbox (if IMAP is configured) are scanned and turned into business signals automatically.

Every day — a Morning Brief lands in your web dashboard and Telegram (and email, if configured). Health score gets updated. The brief is cached — you always see today's, and every surface (terminal, Telegram, MCP, gateway) shows the same one.

Every week — an executive review summarizes what happened, what the patterns are, and what to focus on next.

Everything is stored locally in a SQLite database at ~/.employeeos/brain.db. Nothing goes to any server except the AI provider you choose.

---

The decision loop

Plans follow a full lifecycle you can trace:

observation → plan (pending) → approved → executing → done     → learning
                                                    ↘ failed    → logged (a step errored)
                                                    ↘ blocked   → logged (dangerous op blocked by autonomy level)
             → rejected

Every step is written to an events table. The web dashboard, Telegram, and MCP server all read from the same event history — nothing is synthesized from current state.

---

Install

Three ways to run it — pick whichever works for you.

Option 1: npm (easiest)

npm install -g employeeos
employeeos init

Node.js 20+ required. That's it.

Option 2: Docker

No Node.js needed. Your data persists in ~/.employeeos on your host machine.

docker run -it \
  -p 3001:3001 \
  -v ~/.employeeos:/root/.employeeos \
  -e ANTHROPIC_API_KEY=your_key_here \
  ghcr.io/prasad-bigdp/employeeos:latest \
  init

Or use docker-compose (recommended):

git clone https://github.com/prasad-bigdp/EmployeeOS
cd employeeos
echo "ANTHROPIC_API_KEY=your_key_here" > .env

# First-time setup (interactive)
docker compose run --rm employeeos init

# Start the brain
docker compose up -d
# Open http://localhost:3001

Interactive commands (init, telegram, email) need -it. The start command runs fine detached (-d).

Option 3: Clone and build

npm install -g pnpm
git clone https://github.com/prasad-bigdp/EmployeeOS
cd employeeos
pnpm install
pnpm build

After building:

node apps/terminal/dist/index.js init
# or link globally:
npm link apps/terminal
employeeos init

---

Setup

Run employeeos init — it asks you nine questions and takes about five minutes:

1. Company name, industry, one-sentence description
2. Whether you have multiple brands
3. Your name and email (for personalized briefs)
4. AI provider (see below)
5. Your top business goals
6. Which systems to connect (optional)
7. Documents to read — strategy docs, business plans, anything (optional)
8. Which AI employees to hire
9. How autonomous the brain should be

At the end it generates your first intelligence report and saves everything.

---

Choosing an AI provider

Provider	Auth	Notes
Anthropic Claude	API key	Best quality — console.anthropic.com
Claude Code (Max/Pro/Teams/Enterprise)	Browser OAuth	No API key — uses your subscription
OpenAI Codex (ChatGPT Plus/Pro)	Browser OAuth	No API key — uses your subscription
OpenAI	API key	GPT-4o / o3-mini — platform.openai.com
OpenRouter	API key	400+ models with one key — openrouter.ai
Ollama	None	Free, local, fully private

Claude Code and Codex connect via browser OAuth — no API key copy-pasting. When you select either during employeeos init, a browser tab opens and you log in with your existing subscription account. The session token is stored in ~/.employeeos/config.json.

If you already have claude or codex CLIs installed and authenticated, EmployeeOS will offer to reuse the existing session from ~/.claude/.credentials.json or ~/.codex/auth.json.

Environment variable shortcuts (skip the provider prompt entirely):

ANTHROPIC_API_KEY=sk-ant-...          # Anthropic direct
ANTHROPIC_AUTH_TOKEN=...               # Claude Code OAuth token
CLAUDE_CODE_OAUTH_TOKEN=...            # output of: claude setup-token
OPENAI_API_KEY=sk-...                  # OpenAI direct
OPENROUTER_API_KEY=sk-or-...           # OpenRouter

---

Daily use

employeeos                      Dashboard: goals, health score, latest brief
employeeos start                Start the brain loop + open web UI at :3001
employeeos brief                Generate today's morning brief right now
employeeos think "question"     Ask the brain anything about your company
employeeos status               Health, goals, pending plans
employeeos plans                List AI-generated plans waiting for review
employeeos employees            See who you've hired and their roles
employeeos import <file>        Import metrics from CSV, JSON, or PDF
employeeos browse <url>         Extract metrics from a live dashboard URL
employeeos task <url> <task>    Run an interactive browser workflow on a logged-in site
employeeos github               Connect GitHub (PAT) for issue/PR actions
employeeos connect [app]        Connect SaaS apps via Composio (Slack, Gmail, Notion...)
employeeos email                Set up email notifications + inbox reading
employeeos telegram             Connect Telegram for alerts and plan approval
employeeos skills               Manage custom employee skills
employeeos mcp                  Start the MCP server for Claude Desktop

employeeos start opens http://localhost:3001 with a full web dashboard — real-time terminal showing what the brain is doing, your morning brief, a chat interface, active plans, and your full event history.

---

Getting data in

The brain is more useful the sooner it has real data. There are four ways to feed it:

CSV import

employeeos import
# Choose "Generate sample CSV template"
# Fill it in, then:
employeeos import ~/.employeeos/sample-metrics.csv

The CSV has seven columns: date, category, metric, value, unit, brand, notes

Categories: revenue, marketing, sales, support, hr, finance, operations

PDF import

Drop in any business document — reports, audits, strategy decks, contracts — and the brain extracts business signals with AI:

employeeos import quarterly-review.pdf
employeeos import ~/Downloads/market-research.pdf

The AI reads the document and pulls out concrete signals (revenue figures, headcount changes, market shifts, competitive mentions) and saves each one as a separate observation. Every signal shows up in your event history.

Browser automation

Have the brain open a live dashboard URL and extract the numbers automatically (requires Chrome running with --remote-debugging-port=9222):

employeeos browse https://analytics.example.com/dashboard
employeeos browse https://app.hubspot.com/contacts/deals "extract pipeline metrics"

For interactive tasks like filling forms, clicking buttons, or walking through a logged-in workflow, use:

employeeos task https://app.example.com "create a new ticket for this customer and set priority to high"

If Chrome is already logged in on that site, EmployeeOS can usually reuse the same session by connecting to your existing Chrome profile or a running CDP session.

Webhook receiver

Any external tool can POST directly to your running gateway and the payload becomes an observation immediately — no polling needed:

POST http://localhost:3001/webhook/stripe
POST http://localhost:3001/webhook/hubspot
POST http://localhost:3001/webhook/github
POST http://localhost:3001/webhook/shopify

The source name (stripe, hubspot, etc.) is auto-mapped to a signal category. Any JSON body is accepted. Use this from Zapier, n8n, GitHub Actions, or any platform that supports webhooks.

# Example: Stripe payment failure becomes a finance observation
curl -X POST http://localhost:3001/webhook/stripe \
  -H "Content-Type: application/json" \
  -d '{"type":"payment_intent.payment_failed","amount":4900,"customer":"cus_abc"}'

---

Notifications

Telegram

employeeos telegram

1. Go to @BotFather and create a bot (/newbot)
2. Copy the token it gives you
3. Paste it when prompted — setup detects your chat ID automatically

Your bot will send morning briefs, anomaly alerts, and plan notifications. When a plan needs approval you get inline Approve / Reject buttons right in Telegram. Approvals and rejections are written to the event history immediately.

Bot commands:

• /brief — today's morning brief (cached, instant)
• /status — health score, goals, active employees
• /plans — pending plans with approve/reject buttons
• /ask your question here — ask the brain from your phone

Email (send + inbox reading)

employeeos email

Outbound (SMTP): morning briefs, anomaly alerts, and plan notifications. Works with Gmail (App Password), Outlook, or any SMTP server.

For Gmail App Passwords: Google Account → Security → 2-Step Verification → App passwords.

Inbound (IMAP): after setting up SMTP, you're asked if you also want to read your inbox. If you say yes, the brain connects to your mailbox every hour and extracts business signals from incoming emails — customer inquiries, deal updates, support escalations, partner messages. Only genuine human communication is extracted; newsletters and automated alerts are skipped.

The brain remembers which emails it has already processed (checkpoint stored in the database) so the same email is never imported twice.

---

How plans work

The brain creates plans when employees identify opportunities. Each plan has:

• Employee role — which AI employee created it
• Autonomy level — observe / recommend / execute / autonomous
• Status — pending → approved → done, failed, or blocked

Plans that require approval wait in the queue. You can approve or reject from:

• The web dashboard
• Telegram inline buttons
• The terminal (employeeos plans)

When a plan is executed, the brain:

1. Creates an execution record (stored in the database even on failure)
2. Dispatches each step to the correct tool runner — GitHub native, Composio SaaS, or AI text fallback
3. Tracks every step separately (execution_steps table: started → done/failed)
4. Extracts a learning from the outcome (subject + pattern + confidence)
5. Links the learning back to the execution record so every pattern is traceable
6. Writes step-level events to the history: step.started, step.completed, step.failed

Failed plans show with a red badge in the dashboard and appear in the event feed — nothing is silently dropped.

---

Real integrations

EmployeeOS v1.1 can execute real actions, not just generate text. Plans with structured steps call live APIs:

GitHub (native)

employeeos github

Connect a Personal Access Token and EmployeeOS can:

• Create issues automatically from anomaly observations
• Comment on PRs with execution summaries
• Open pull requests as plan steps
• Add labels and close issues
• Read open issue/PR counts as business signals