ohwow 0.2.0 → 0.3.0

package/README.md

@@ -6,112 +6,241 @@
 [![npm downloads](https://img.shields.io/npm/dm/ohwow)](https://www.npmjs.com/package/ohwow)
 [![Discord](https://img.shields.io/badge/Discord-join-5865F2)](https://discord.gg/WUGnGqceeY)
 
-**Your AI team that runs on your laptop. Agents that learn, message customers, browse the web, and control your desktop. Costs $0.**
+**An AI team that runs on your laptop. Agents that learn your patterns, message your customers, automate your operations, and actually understand what your business needs right now. Free. Open source. Your data stays on your machine.**
 
 <p align="center">
   <img src="docs/demo.gif" alt="ohwow demo" width="800">
 </p>
 
-ohwow is an open source AI business operating system. A team of AI agents that live on your laptop, handle your CRM, message your customers on WhatsApp, automate your workflows, browse the web, and now control your desktop. All running locally. All free. No cloud required.
-
-## Quick Start
-
 ```bash
 npm install ohwow -g
 ohwow
 ```
 
-A setup wizard walks you through connecting to [Ollama](https://ollama.com), picking a model, and selecting agents for your business type. Running in under 5 minutes.
+Running in under 5 minutes. A setup wizard connects to [Ollama](https://ollama.com), picks a model, and builds an AI team for your business type.
 
-<p align="center">
-  <img src="docs/onboarding.gif" alt="ohwow onboarding" width="800">
-</p>
+---
+
+## What a day looks like with ohwow
+
+**7:45 AM** — You open your laptop. ohwow noticed you always start around this time. Your morning briefing is ready: "3 tasks completed overnight. 1 needs your eye (a customer contract with unusual terms). 2 leads replied to yesterday's outreach. Your Sales Agent's follow-up is queued for 9am."
+
+**8:00 AM** — You say: "What should I focus on today?" ohwow knows you're at growth stage 2 (Attract). It responds: "You're over-indexing on content creation this week. Your growth stage needs more outreach. Your Sales Agent has 3 warm leads that haven't been contacted. Want me to draft follow-ups?"
+
+**8:15 AM** — You approve the follow-ups. The Sales Agent sends personalized WhatsApp messages to each lead, referencing their specific context from your CRM. No templates. Each message reads like you wrote it.
+
+**10:30 AM** — You're deep in product work. A customer emails with a support question. ohwow detects it, routes it to the Support Agent, which drafts a response. Because your cognitive load is high (3 open approvals, deep work mode), it batches the notification instead of interrupting. You'll see it at your next natural break.
 
-## Talk to it like a person
+**2:00 PM** — ohwow notices your energy dips after lunch (it learned this from 30 days of watching your activity patterns). It holds the complex research report that just completed, knowing you'll evaluate it better in the morning. Instead, it surfaces a simple approval that takes 10 seconds.
 
-The orchestrator is a conversational assistant with 150+ tools. Open the Chat tab and speak naturally:
+**4:00 PM** — A lead responds positively on WhatsApp. ohwow's Sales Agent wants to send a pricing proposal. It could auto-send (it's earned that trust after 47 successful outreach tasks with 94% approval), but the amount is above the auto-approve threshold. You get a one-line notification: "Ready to send pricing to Acme Corp. $4,500/mo proposal. Approve?"
+
+**6:15 PM** — You close your laptop. ohwow stops all non-critical notifications. Your agents keep working: the Content Writer drafts tomorrow's blog post, the Researcher compiles a competitive analysis you asked for this morning. Results will be waiting when you open up tomorrow.
+
+**End of day**: 12 tasks completed across 4 agents. 3 leads contacted. 1 support ticket resolved. 1 blog draft ready. You spent 20 minutes on approvals. The rest was your work.
+
+---
+
+## How it actually works
+
+### Talk to it like a person
+
+The orchestrator understands natural language with 150+ tools behind it:
 
 | What you say | What happens |
 |---|---|
-| "Run the content writer on this week's blog post" | Dispatches a task to that agent immediately |
-| "What failed today?" | Lists recent failed tasks with details |
-| "Schedule outreach every weekday at 9am" | Creates a cron schedule for the agent |
-| "Send a WhatsApp to the team: launching Friday" | Sends the message through your connected WhatsApp |
-| "Open Figma and export the hero banner as PNG" | Takes over your desktop, opens the app, clicks through menus, saves the file |
-| "Plan out researching 5 new leads this week" | Creates a multi-step plan with agent assignments, waits for your approval |
-| "Show me the business pulse" | Returns task stats, contact pipeline, costs, and streaks |
-| "Create a project for the website redesign" | Creates a project with a Kanban board |
+| "Follow up with everyone who opened my last email" | Finds contacts with email opens, drafts personalized follow-ups, sends via WhatsApp or email |
+| "Research our top 5 competitors and create a comparison" | Launches the Research Agent with deep web search, compiles findings into a structured report |
+| "Schedule outreach every weekday at 9am" | Creates a recurring schedule. The agent picks leads from your CRM, personalizes messages, and sends them on time |
+| "Open Figma and export the hero banner as PNG" | Takes over your desktop, opens the app, navigates to the file, exports it, saves to your folder |
+| "How's the business doing?" | Shows your eudaimonia score (workspace flourishing), task stats, lead pipeline, agent efficiency, and growth stage guidance |
+| "Create a project for the website redesign" | Creates a Kanban board, suggests task breakdown, assigns agents to each phase |
+| "Send a WhatsApp to the team: launching Friday" | Sends through your connected WhatsApp. No API needed. Uses your actual WhatsApp number |
+| "What should I focus on this week?" | Analyzes your growth stage, current work balance, goal velocity, and team capacity. Gives specific, actionable recommendations |
+
+### Your agents learn and improve
+
+ohwow agents aren't stateless. They remember what worked and what didn't:
+
+- After the Content Writer produces 50 blog posts, it knows your brand voice, preferred structure, and which topics get approved immediately vs revised
+- After the Sales Agent sends 200 outreach messages, it knows which opening lines get responses and which get ignored
+- After the Researcher completes 30 deep dives, it knows which sources you trust and how detailed you want the analysis
+
+This isn't "fine-tuning." It's persistent memory, skill synthesis, and pattern mining that builds real expertise over time. Each agent develops its own character: some become meticulous researchers, others become fast-moving closers.
+
+### It knows your business stage
+
+A startup just launching needs different work than an established company scaling. ohwow knows the difference:
+
+| Growth Stage | Revenue | What ohwow prioritizes |
+|---|---|---|
+| **Launch** | $0-$1K | Selling. Not building more features. Not researching competitors. Getting first customers |
+| **Attract** | $1K-$10K | Lead flow. Content that brings people in. One channel, mastered |
+| **Systemize** | $10K-$25K | Automating what works. SOPs. Reducing founder dependency |
+| **Focus** | $25K-$50K | Cutting the bottom 20%. Serving ideal customers. Unit economics |
+| **Expand** | $50K-$100K | Second product or market. Validated before scaled |
+| **Structure** | $250K-$500K | Delegation. The founder stops doing execution work |
+
+When you ask "what should I focus on?", the answer comes from practical wisdom about your specific stage, not generic advice.
+
+### It respects that you're human
+
+Most productivity tools treat you like a machine that processes tasks. ohwow doesn't.
+
+- **It learns your rhythm.** Morning person? Complex approvals arrive at 9am. Afternoon slump? Only quick tasks surface after 2pm.
+- **It detects overload.** When you have too many open decisions, it stops adding work and starts batching, prioritizing, and filtering.
+- **It respects boundaries.** If you always stop responding at 6pm, ohwow stops notifying. No setting required. It learns by watching.
+- **It suggests rest.** After a week of sprinting, it shifts work toward reflective tasks and away from high-pressure action items.
+
+---
+
+## Real scenarios
+
+### For a solo e-commerce founder
+
+You sell handmade candles on Shopify. You spend 3 hours a day on customer emails, social media, and supplier follow-ups.
+
+With ohwow: the Support Agent handles customer questions via WhatsApp (you approve the first few, then trust builds and it handles most autonomously). The Content Writer creates daily Instagram captions and weekly blog posts about your craft. The Sales Agent follows up with wholesale leads from your last trade show. You focus on making candles.
+
+### For a SaaS founder with a small team
+
+You and 2 engineers are building a developer tool. Marketing, support, and sales fall on you.
+
+With ohwow: agents handle lead outreach, support ticket triage, competitive research, and content creation. The system knows you're at stage 2 (Attract) and pushes outreach over feature building. When a lead responds on WhatsApp, the Sales Agent drafts a response referencing their specific use case from your CRM. Your team reviews agent output in the dashboard. Trust builds per domain: the Content Writer runs autonomously, the Sales Agent still needs approval for pricing discussions.
+
+### For an agency managing multiple clients
+
+You run a marketing agency with 10 clients. Each needs weekly reports, social posts, and campaign analysis.
+
+With ohwow: each client gets dedicated agents. The Researcher pulls analytics. The Content Writer drafts social posts in each client's brand voice. The Reporter compiles weekly performance reports. Agents learn each client's preferences separately. Desktop automation exports graphics from Canva, screenshots from analytics dashboards. Multi-device mesh lets your office Mac Mini run overnight while you review results on your MacBook in the morning.
+
+### For a privacy-focused business
+
+You handle sensitive customer data and can't use cloud AI platforms.
+
+With ohwow: everything runs locally with Ollama. No data leaves your machine. No API calls to external LLMs if you don't want them. Local SQLite database. Local model inference. WhatsApp messages stay on your device. You get full AI automation with zero cloud dependency.
+
+---
 
 ## Features
 
 | Category | What you get |
 |---|---|
-| AI Agents | 48 pre-built agents across 6 business types, persistent memory, RAG retrieval |
-| Orchestrator | 150+ tools, natural language chat interface for everything |
-| Desktop Control | Full macOS desktop automation: mouse, keyboard, screen capture. Your agents operate any app on your computer. (macOS only) |
-| Messaging | WhatsApp + Telegram built in, auto-routing to agents |
-| Browser | Local Chromium automation (navigate, click, fill, screenshot, extract) |
-| Voice | Local STT/TTS (Whisper, Piper) with cloud fallbacks |
-| CRM | Contacts, pipeline, events, analytics, all stored locally |
-| Scheduling | Cron schedules + proactive nudge engine every 30 minutes |
-| Workflows | DAG-based multi-agent execution graphs with conditions |
-| Multidevice | Zero-config mDNS mesh, automatic task routing across machines |
-| MCP | External tool integration via Model Context Protocol |
-| A2A | Google Agent-to-Agent protocol over JSON-RPC 2.0 |
-| Sandbox | Isolated JavaScript execution (no fs/net/process access) |
+| **AI Agents** | 48 pre-built agents across 6 business types. Persistent memory. Tool mastery. Real expertise over time |
+| **Orchestrator** | 150+ tools. Natural language interface. Growth-stage-aware recommendations |
+| **Desktop Control** | Full macOS automation: mouse, keyboard, screen capture. Your agents operate any app on your computer |
+| **Messaging** | WhatsApp + Telegram built in. Uses your real number. Auto-routing to the right agent |
+| **Browser** | Local Chromium automation: navigate, click, fill forms, screenshot, extract data |
+| **CRM** | Contacts, pipeline, events, analytics. All stored locally. Agents use it to personalize outreach |
+| **Scheduling** | Cron schedules + smart timing based on opportunity detection |
+| **Workflows** | Multi-step automation graphs. Parallel execution. Conditions and branching |
+| **Multi-device** | Zero-config mesh across your machines. Tasks route to the best device. Self-healing if one goes down |
+| **Physical I/O** | Connect Arduino, ESP32, sensors, actuators. Your office becomes smart |
+| **MCP** | External tool integration via Model Context Protocol |
+| **A2A** | Agent-to-Agent protocol for connecting with other AI systems |
+| **Cognitive Architecture** | 7-layer philosophical system powering everything under the hood |
+
+## Use with Claude Code
+
+ohwow works as a Claude Code plugin. 25 tools become available in your Claude conversations.
 
-## Desktop Control
+```bash
+claude plugin install ohwow-fun/ohwow
+```
+
+Or add to any project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ohwow": {
+      "command": "npx",
+      "args": ["-y", "ohwow", "mcp-server"]
+    }
+  }
+}
+```
 
-Your agents aren't trapped inside a chat window. They can use your computer.
+**Example**: "Research the top 5 competitors in our space, add the findings to the knowledge base, then create a contact for each CEO." Claude uses ohwow's research, knowledge, and CRM tools seamlessly.
 
-ohwow agents see your screen, move the mouse, type on the keyboard, and operate any macOS app. Not through brittle scripts or accessibility hacks. They look at what's on screen, reason about what to do next, and act. The same way you would, but without getting distracted.
+## Desktop Control
 
-**How it works:** the agent takes a screenshot, analyzes it with a vision model, decides the next action (click, type, scroll, key press), executes it, then takes another screenshot to see the result. This perception/reasoning/action loop repeats until the task is done.
+Your agents aren't trapped in a chat window. They operate your computer.
 
 ```
 You: "Fill out the Q1 expense report in Google Sheets using last month's receipts folder"
 
 ohwow:
-  1. Opens Finder, navigates to the receipts folder
+  1. Opens Finder, navigates to receipts
   2. Opens Google Sheets in Chrome
-  3. Reads each receipt, types the amounts into the right cells
+  3. Reads each receipt, types amounts into the right cells
   4. Double-checks totals
   5. Done. You were making coffee the whole time.
 ```
 
-**Safety first.** Desktop control requires your explicit permission before activating. You can stop the agent at any point. Dangerous actions (typing in Terminal, changing system settings) trigger additional approval. An emergency stop halts everything instantly.
+The agent takes a screenshot, analyzes it with a vision model, decides the next action, executes it, then screenshots again to see the result. This perception/reasoning/action loop repeats until the task is done.
 
-**Works with Dispatch.** Connect to [ohwow.fun](https://ohwow.fun) and trigger desktop tasks from your phone. Start a task on the train, your MacBook at home does the work. Check progress from the dashboard.
+**Safety first.** Desktop control requires explicit permission. Emergency stop halts everything instantly. Dangerous actions (Terminal, system settings) trigger additional approval.
 
-> Desktop control currently supports macOS only. All other features (agents, chat, browser automation, voice, CRM, scheduling, MCP) work on macOS, Linux, and Windows. See [Windows Setup Guide](docs/windows-setup.md) for details.
+## Multi-device Mesh
 
-## Who is this for?
+```
+Mac Mini (home office)       MacBook (on the go)          Raspberry Pi (warehouse)
+┌────────────────┐          ┌────────────────┐          ┌────────────────┐
+│ WhatsApp Agent  │◄─mesh──►│ Research Agent  │◄─mesh──►│ Temp Sensor     │
+│ Desktop Tasks   │          │ Browser Auto    │          │ Motion Detect   │
+│ Overnight Work  │          │ Mobile Review   │          │ Inventory Scan  │
+└────────────────┘          └────────────────┘          └────────────────┘
+```
 
-- **Solo founders** automating marketing, outreach, and ops with zero budget
-- **Busy operators** who want an AI team that handles the repetitive screen work while they focus on growth
-- **Small teams** that need agents coordinating across devices
-- **Agencies** managing operations for multiple clients
-- **Privacy-conscious businesses** that need AI automation without cloud lock-in
-- **Developers** building custom agents with the orchestrator, MCP tools, and desktop control APIs
+Zero configuration. Devices discover each other on your network. Tasks go to the best device for the job. If your Mac Mini discovers that a lead's website is down, your MacBook knows instantly. If one device goes offline, another takes over its responsibilities.
 
 ## Why ohwow?
 
-| | Zapier | n8n | Make | OpenClaw | **ohwow** |
-|---|---|---|---|---|---|
-| Runs on your machine | No | Self-host option | No | Yes | **Yes, always** |
-| Desktop control | No | No | No | Yes | **Yes, with safety guards** |
-| AI agents with persistent memory | No | Yes (LangChain nodes) | No | Partial | **Yes, agents learn over time** |
-| Cost to start | $20+/mo | Free (self-host) | $10+/mo | Free | **$0 with Ollama** |
-| Pre-built business agents | No | No | No | No | **48 agents, 6 biz types** |
-| WhatsApp + Telegram | Plugin | Plugin | Plugin | No | **Built in** |
-| CRM + contacts | No | No | No | No | **Built in** |
-| Multi-device mesh | No | No | No | No | **Zero-config** |
-| Browser automation | No | Partial | No | Yes | **Built in (Chromium)** |
-| Workflow DAGs | Yes | Yes | Yes | No | **Yes, with conditions + parallel** |
-| Phone dispatch | No | No | No | No | **Yes, via ohwow.fun** |
-| Your data stays local | No | Optional | No | Yes | **Always** |
-
-> Comparison as of March 2026. We love what OpenClaw, n8n, and others are building. ohwow focuses on a different problem: a complete AI business runtime, not just a single agent or workflow tool.
+| | Zapier | n8n | Make | **ohwow** |
+|---|---|---|---|---|
+| Runs on your machine | No | Self-host option | No | **Yes, always** |
+| Desktop control | No | No | No | **Yes, with safety guards** |
+| AI agents with real memory | No | Partial | No | **Yes, agents build expertise** |
+| Cost to start | $20+/mo | Free (self-host) | $10+/mo | **$0 with Ollama** |
+| Pre-built business agents | No | No | No | **48 agents, 6 business types** |
+| WhatsApp + Telegram | Plugin | Plugin | Plugin | **Built in** |
+| CRM + contacts | No | No | No | **Built in** |
+| Multi-device mesh | No | No | No | **Zero-config** |
+| Knows your growth stage | No | No | No | **Yes, adapts priorities** |
+| Respects your energy/stress | No | No | No | **Yes, bio-aware** |
+| Your data stays local | No | Optional | No | **Always** |
+
+## Cloud (optional)
+
+Connect to [ohwow.fun](https://ohwow.fun) for cloud features on top of the free local runtime:
+
+- **Phone dispatch**: assign tasks to your computer from your phone
+- **OAuth integrations**: Gmail, Slack, and more
+- **AI site generator**: with hosting and custom domains
+- **Fleet dashboard**: manage all your devices from one place
+- **Collective intelligence**: visualize what your agents have learned
+- **Work ontology dashboard**: eudaimonia score, growth stage guidance
+
+All local features work without cloud. See [pricing](https://ohwow.fun/pricing) for plans starting at $29/mo.
+
+## Under the Hood
+
+For those who want to understand the architecture: ohwow is built on a seven-layer philosophical cognitive architecture. Each layer addresses a distinct dimension of intelligence, grounded in philosophy from Aristotle to modern cognitive science.
+
+```
+Layer 7: BIOS       — Respects human biology (energy, stress, boundaries)
+Layer 6: Symbiosis  — Models human-AI collaboration (trust, handoffs, mutual learning)
+Layer 5: Soul       — Tracks identity for agents and humans (values, blind spots, growth)
+    Persona         — Real-time behavioral profiling (circadian, load, communication style)
+Layer 4: Mesh       — Distributed consciousness across devices (propagation, shared body, self-healing)
+Layer 3: Work       — Purpose-driven execution (growth stage wisdom, work classification, flourishing)
+Layer 2: Body       — Physical + digital embodiment (organs, nervous systems, affordances, PID controllers)
+Layer 1: Brain      — Cognitive cycle: perceive → deliberate → act (prediction, reflection, dialectic)
+Layer 0: Runtime    — Orchestrator, engine, 150+ tools, DB, API, scheduling, messaging
+```
+
+115+ modules. 28,000+ lines. Every philosophical concept is load-bearing architecture: remove any one and the system degrades measurably. See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full technical breakdown.
 
 ## Self-hosting
 
@@ -120,11 +249,8 @@ ohwow:
 | `ohwow` | Start the TUI (default) |
 | `ohwow --daemon` | Start daemon in foreground (for systemd/launchd/Docker) |
 | `ohwow stop` | Stop the daemon |
-| `ohwow status` | Check daemon status (PID and port) |
+| `ohwow status` | Check daemon status |
 | `ohwow logs` | Tail daemon logs |
-| `ohwow restart` | Restart the daemon |
-
-The runtime serves a web UI at `http://localhost:7700`. Override the port with `OHWOW_PORT`.
 
 Docker:
 
@@ -132,37 +258,22 @@ Docker:
 docker run -d --name ohwow -p 7700:7700 -v ~/.ohwow:/root/.ohwow ohwow
 ```
 
-## Cloud
-
-Connect to [ohwow.fun](https://ohwow.fun) for cloud features on top of the free local runtime:
-
-- **Desktop dispatch** from your phone. Assign tasks to your MacBook while you're out.
-- **OAuth integrations** (Gmail, Slack, and more)
-- **Cloud task dispatch** from the web dashboard or mobile
-- **AI site generator** with hosting and custom domains
-- **Webhook relay** for external services
-- **Fleet management** across devices
-
-All local features work without cloud. See [pricing](https://ohwow.fun/pricing) for plans starting at $29/mo.
-
 ## Requirements
 
 - Node.js 20+
 - [Ollama](https://ollama.com) for local models
 - Optional: Anthropic API key (for Claude models)
 - Optional: Playwright browsers (`npx playwright install chromium`) for browser automation
-- Optional: macOS Accessibility permission for desktop control (macOS only)
-- Optional: Visual Studio C++ Build Tools on Windows for `better-sqlite3` native module
+- Optional: macOS Accessibility permission for desktop control
 
 ## Troubleshooting
 
 | Problem | Solution |
 |---------|----------|
-| `better-sqlite3` build fails | Install build tools: `xcode-select --install` (macOS), `sudo apt install build-essential python3` (Linux), or Visual Studio C++ Build Tools (Windows) |
+| `better-sqlite3` build fails | Install build tools: `xcode-select --install` (macOS), `sudo apt install build-essential python3` (Linux) |
 | Ollama not detected | Ensure Ollama is running (`ollama serve`) and accessible at `http://localhost:11434` |
 | Port 7700 in use | Set `OHWOW_PORT=7701` or any free port |
 | WhatsApp QR expired | Restart ohwow and scan the new QR within 60 seconds |
-| `EACCES` on global install | Use `npm install ohwow -g --prefix ~/.npm-global` or fix npm permissions |
 
 ## Community
 
@@ -170,7 +281,6 @@ All local features work without cloud. See [pricing](https://ohwow.fun/pricing)
 - [Contributing](./CONTRIBUTING.md)
 - [Architecture](./ARCHITECTURE.md)
 - [Security](./SECURITY.md)
-- [Governance](./GOVERNANCE.md)
 - Email: ogsus@ohwow.fun
 
 ## License