# SophiaClaw **Governance-First AI Infrastructure** — Autonomous agents with complete audit trails, policy enforcement, and user control. [![Build Status](https://github.com/sophiaclaw/sophiaclaw/actions/workflows/ci.yml/badge.svg)](https://github.com/sophiaclaw/sophiaclaw/actions) [![Test Coverage](https://img.shields.io/badge/coverage-80%25-green)](https://github.com/sophiaclaw/sophiaclaw) [![npm version](https://img.shields.io/npm/v/sophiaclaw)](https://www.npmjs.com/package/sophiaclaw) [![Documentation](https://img.shields.io/badge/docs-latest-blue)](https://docs.sophiaclaw.ai) [![Discord](https://img.shields.io/discord/sophiaclaw)](https://discord.gg/sophiaclaw) [![License](https://img.shields.io/github/license/sophiaclaw/sophiaclaw)](./LICENSE) --- ## Overview **SophiaClaw** is open-source AI infrastructure that brings frontier AI capabilities to your communication channels—Telegram, WhatsApp, Discord, Slack, iMessage, Signal, and more. Built with **governance-first architecture**, every action is auditable, policy-checked, and under your control. ### Why SophiaClaw? | Traditional AI | SophiaClaw | | --------------- | ------------------------------------- | | Single platform | **Omnichannel** - 9+ channels | | Black-box | **Transparent** - full audit trails | | Vendor's cloud | **Your infrastructure** - self-hosted | | One AI provider | **Multi-provider** - any LLM | | Closed source | **Open source** - MIT license | --- ## Quick Start ### 5-Minute Setup ```bash # Install (Node.js 22+ required) npm install -g sophiaclaw@latest # Run interactive onboarding sophiaclaw onboard ``` The wizard will: 1. ✅ Check system requirements 2. ✅ Configure the Gateway (local AI server) 3. ✅ Set up your first channel (Telegram recommended) 4. ✅ Install as background service (optional) ### First Conversation ```bash # Terminal sophiaclaw agent --message "What's on my calendar today?" # Telegram (after setup) Message your bot: "/agent What's on my calendar today?" ``` → **[Full Quickstart Guide](./docs/getting-started.md)** --- ## Architecture ``` ┌─────────────────────────────────────────────────────────┐ │ SophiaClaw Architecture │ ├─────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Telegram │ │ WhatsApp │ │ Discord │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ └────────────────┼────────────────┘ │ │ ▼ │ │ ┌───────────────────────────────────────────────┐ │ │ │ Message Routing & Governance │ │ │ │ • Intent Recognition • Policy Enforcement │ │ │ │ • Audit Logging • Rate Limiting │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────────────────────────────────────┐ │ │ │ AI Agent Core │ │ │ │ • Memory & Context • Tool Execution │ │ │ │ • Planning • Response Generation │ │ │ └───────────────────────────────────────────────┘ │ │ ┌──────────────┬──────────────┐ │ │ ▼ ▼ ▼ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ OpenAI │ │ Anthropic│ │ Ollama │ │ │ │ GPT-4 │ │ Claude │ │ Local │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ └─────────────────────────────────────────────────────────┘ ``` See **`docs/diagrams/public/high-level-architecture.drawio`** for full diagram. --- ## Governance Model Every SophiaClaw interaction follows this loop: ``` You Ask → Intent Captured → Policy Check → Execute → Audit Logged ↑ ↓ └────────────── You Review & Correct ─────────┘ ``` ### Five Pillars | Pillar | What It Does | Business Value | | ---------------------- | --------------------------------- | ------------------------------- | | **Intent Capture** | AI writes what it thinks you want | Prevents misunderstandings | | **Policy Enforcement** | Rules checked before every action | Enforces your constraints | | **Approval Gates** | High-risk ops pause for approval | Can't accidentally cause damage | | **Audit Trail** | Immutable logs with timestamps | Compliance-ready documentation | | **Conflict Detection** | Prevents agent collisions | Safe to scale across teams | → **[Governance Framework](./docs/governance.md)** --- ## Key Features ### 🏛️ Governance-First - **Intent Locking**: Every action tracked from intent to execution - **Policy Engine**: Custom rules enforced automatically - **Approval Gates**: Human-in-the-loop for high-risk operations - **Immutable Audit**: Complete log of every decision - **Conflict Detection**: Prevents simultaneous overwrites ### 🔒 Security - **Credential Encryption**: AES-256-GCM with OS keychain - **Log Integrity**: SHA-256 hashing with verification - **Sandboxed Execution**: File system jail, process restrictions - **Rate Limiting**: 100 req/min per scope - **Circuit Breakers**: Protects external dependencies ### 🧠 Multi-Provider AI - **OpenRouter**: Route to 100+ LLMs cost-efficiently - **Direct Providers**: Anthropic, OpenAI, Google, Groq - **Local Models**: Ollama, LM Studio - **Budget Tracking**: Monthly limits with alerts - **Performance Metrics**: Latency, tokens/sec tracking ### 📱 Omnichannel - **Telegram**: Recommended for teams - **Discord**: Community management - **Slack**: Enterprise workflows - **WhatsApp**: Personal assistant - **Signal**: Privacy-focused - **iMessage**: Native macOS - **Email**: IMAP/SMTP integration - **Web**: WebSocket chat interface ### 🖥️ Native Apps - **macOS**: SwiftUI menubar app - Model Settings UI with provider selection - Expert Mode toggle (progressive disclosure) - Budget tracking with visual progress - Accessibility: WCAG 2.1 AA (108 labels) - **iOS**: Coming Q2 2026 - **Android**: Coming Q2 2026 - **TUI**: Terminal UI with burst coalescing, OSC8 links ### 🧩 Plugin System - **Extension SDK**: Build custom channels, tools, auth providers - **MCP Integration**: Model Context Protocol support - **HTTP Auth**: OAuth2 flows for new providers - **Channel Registry**: Pluggable messaging channels --- ## Documentation | Audience | Start Here | | ------------------------ | -------------------------------------------------------------------------------- | | **New Users** | [docs/getting-started.md](docs/getting-started.md) | | **macOS App Users** | [docs/platforms/mac/README.md](docs/platforms/mac/README.md) | | **Developers** | [docs/opensource/DOCUMENTATION_INDEX.md](docs/opensource/DOCUMENTATION_INDEX.md) | | **Security Researchers** | [SECURITY.md](SECURITY.md) | | **Contributors** | [CONTRIBUTING.md](CONTRIBUTING.md) | | **Business Owners** | [docs/governance/README.md](docs/governance/README.md) | ### Algorithm Documentation 33 detailed algorithm docs (18k+ lines): - **Core Infrastructure**: Circuit Breaker, Device Pairing, Log Integrity, mDNS, SSRF Protection - **Security**: Credential Encryption, Constant-Time Comparison, Gateway Auth - **Governance**: Audit Engine, Policy Evaluation, Intent Lifecycle - **Gateway/Network**: Rate Limiter, Connection Manager, IP Resolution - **Memory/Search**: Fallback Manager, Index Manager, QMD Backend - **UI/UX**: TUI Engine, macOS AppState, Permission Manager → **[Full Algorithm Index](docs/opensource/ALGORITHM_INVENTORY.md)** ### Architecture Diagrams **Internal (9 technical)**: - System Architecture - Gateway Request Flow - Circuit Breaker State Machine - Device Pairing Protocol - Governance Gate Decision Tree - Memory Fallback Architecture - Auth Flow - TUI Event Loop - Credential Encryption Flow **Public (6 user-facing)**: - Value Proposition - High-Level Architecture - User Journey - Governance Loop - Platform Ecosystem - Security Model → **[Diagram Directory](docs/diagrams/)** --- ## Installation ### macOS (Native App) ```bash # Download latest DMG curl -L https://github.com/sophiaclaw/sophiaclaw/releases/latest/download/SOPHIAClaw.dmg -o SOPHIAClaw.dmg open SOPHIAClaw.dmg ``` ### Linux ```bash # Install via npm npm install -g sophiaclaw # Or build from source git clone https://github.com/sophiaclaw/sophiaclaw cd SOPHIAClaw pnpm install pnpm build ``` ### Windows (WSL2) ```bash # Install in WSL2 Ubuntu npm install -g sophiaclaw sophiaclaw gateway run --bind loopback # Access from Windows via \\wsl$ ``` ### Docker ```bash docker run -d \ -p 37521:37521 \ -v ~/.sophiaclaw:/root/.sophiaclaw \ sophiaclaw:latest ``` → **[Platform-Specific Guides](docs/platforms/)** --- ## Tests ```bash # Run all tests pnpm test # Coverage report pnpm test:coverage # Live tests (real API keys) CLAWDBOT_LIVE_TEST=1 pnpm test:live # Performance benchmarks pnpm test:benchmarks ``` **Test Suite**: 2000+ tests - Unit: Core logic, algorithms - Integration: Gateway, channels, memory - E2E: Full workflows (onboarding, message send) - Benchmarks: Performance regression detection --- ## Community Edition TODO Status **13/13 (100%) Complete** ✅ | # | Task | Status | | --- | ------------------------ | -------------- | | 1 | Credential Encryption | ✅ Implemented | | 2 | Log Integrity Hashing | ✅ Implemented | | 3 | UI Text Cleanup | ✅ Complete | | 4 | Circuit Breakers | ✅ Implemented | | 5 | Persona Onboarding | ✅ Implemented | | 6 | Log Storage Optimization | ✅ Implemented | | 7 | Enhanced Error Handling | ✅ Implemented | | 8 | Resource Monitoring | ✅ Implemented | | 9 | Model Configuration | ✅ Implemented | | 10 | Design System | ✅ Implemented | | 11 | Progressive Disclosure | ✅ Implemented | | 12 | Security Testing Suite | ✅ Implemented | | 13 | Performance Benchmarking | ✅ Implemented | → **[Full TODO Tracker](docs/multi-role-analysis/COMMUNITY_EDITION_TODO.md)** --- ## Contributing 1. **Fork** → create feature branch 2. **TDD** → tests first (80% coverage required) 3. **Format**: `pnpm format` 4. **Lint**: `pnpm lint` 5. **Type-check**: `pnpm tsgo` 6. **Test**: `pnpm test` 7. **PR** → AI-assisted code disclosure required → **[Contribution Guide](CONTRIBUTING.md)** --- ## Security - **Vulnerability Disclosure**: Report to `security@thalamus.ai` - **Response Timeline**: - Critical: 24 hours - High: 72 hours - Medium: 7 days - **Bug Bounty**: Available for critical issues → **[Security Policy](SECURITY_ENHANCED.md)** --- ## License **MIT License** — use it, modify it, self-host it. You own it. → **[LICENSE](LICENSE)** --- Built with 💜 by [Thalamus](https://getthalamus.ai) **The AI That Actually Gives a Damn™** [Get Started](docs/getting-started.md) • [For SMB Owners](docs/governance/README.md) • [Governance](docs/governance.md)