SophiaClaw

Governance-First AI Infrastructure — Autonomous agents with complete audit trails, policy enforcement, and user control.

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

# 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

# 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

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

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 | | macOS App Users | docs/platforms/mac/README.md | | Developers | docs/opensource/DOCUMENTATION_INDEX.md | | Security Researchers | SECURITY.md | | Contributors | CONTRIBUTING.md | | Business Owners | 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

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

Installation

macOS (Native App)

# Download latest DMG
curl -L https://github.com/sophiaclaw/sophiaclaw/releases/latest/download/SOPHIAClaw.dmg -o SOPHIAClaw.dmg
open SOPHIAClaw.dmg

Linux

# 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)

# Install in WSL2 Ubuntu
npm install -g sophiaclaw
sophiaclaw gateway run --bind loopback
# Access from Windows via \\wsl$

Docker

docker run -d \
  -p 37521:37521 \
  -v ~/.sophiaclaw:/root/.sophiaclaw \
  sophiaclaw:latest

→ Platform-Specific Guides

Tests

# 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

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

Security

• Vulnerability Disclosure: Report to [email protected]
• Response Timeline:
  • Critical: 24 hours
  • High: 72 hours
  • Medium: 7 days
• Bug Bounty: Available for critical issues

→ Security Policy

License

MIT License — use it, modify it, self-host it.

You own it.

→ LICENSE

Built with 💜 by Thalamus

The AI That Actually Gives a Damn™

Get Started • For SMB Owners • Governance