hybridclaw

# HybridClaw

[![CI](https://github.com/HybridAIOne/hybridclaw/actions/workflows/ci.yml/badge.svg)](https://github.com/HybridAIOne/hybridclaw/actions/workflows/ci.yml)
[![coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/HybridAIOne/hybridclaw/gh-pages/badge/coverage.json)](https://github.com/HybridAIOne/hybridclaw/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@hybridaione/hybridclaw)](https://www.npmjs.com/package/@hybridaione/hybridclaw)
[![Node](https://img.shields.io/badge/node-22.x-5FA04E?logo=node.js&logoColor=white)](https://nodejs.org/en/download)
[![License](https://img.shields.io/github/license/HybridAIOne/hybridclaw)](https://github.com/HybridAIOne/hybridclaw/blob/main/LICENSE)
[![Docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://hybridaione.github.io/hybridclaw/)
[![Powered by HybridAI](https://img.shields.io/badge/powered%20by-HybridAI-blueviolet)](https://hybridai.one)
[![Discord](https://img.shields.io/badge/Discord-join%20chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/jsVW4vJw27)

<img width="540" height="511" alt="image" src="docs/hero.png" />

Personal AI assistant for Discord, Microsoft Teams, iMessage, WhatsApp, email,
web, and terminal, powered by [HybridAI](https://hybridai.one).

HybridClaw keeps one assistant brain across team chat, inbox, browser, and
document workflows with shared memory, approvals, scheduling, and bundled
skills for office docs, GitHub, Notion, Stripe, WordPress, Google Workspace,
and Apple apps.
Runtime secrets live in an encrypted local store with separate master-key
sourcing, SecretRefs can keep config values out of plaintext JSON, and
gateway-side auth injection lets the agent call authenticated APIs without
seeing the raw credential.
Portable `.claw` packages can snapshot an agent workspace plus bundled skills
and plugins for transfer or backup, and persistent browser profiles let the
agent reuse authenticated web sessions for later browser automation.
OpenClaw and Hermes Agent homes can also be imported into HybridClaw agent
workspaces with migration commands that preview compatible files, config, and
optional secrets before writing anything.
Local plugins can extend the gateway with typed manifests, plugin tools,
memory layers, prompt hooks, lifecycle hooks, and fixed plugin-owned inbound
webhook routes, including the installable QMD-backed memory layer shipped in
`plugins/qmd-memory`.
Web chat and TUI can attach current-turn files, and inline context references
like `@file:src/app.ts`, `@diff`, or `@url:https://example.com/spec` can
ground a turn without pasting raw content.

Operators can also health-check the runtime with `hybridclaw doctor`, tune
skill availability globally or per channel, and review adaptive skill health
and amendment history from the CLI, TUI, or admin surfaces.
Concierge routing can ask about urgency before longer jobs and map execution
to profile-specific models, while tracked runtime config revisions make local
config changes auditable and reversible.
For turn-level debugging, gateway start/restart can also persist best-effort
redacted prompts, responses, and tool payloads with `--log-requests`.

## Install from npm

```bash
npm install -g @hybridaione/hybridclaw
hybridclaw onboarding
```

Prerequisites: Node.js 22. Docker is recommended when you want the default
container sandbox. The published install bootstraps the packaged container
runtime dependencies during `npm install -g`.
The current release tag is
[v0.10.0](https://github.com/HybridAIOne/hybridclaw/releases/tag/v0.10.0).
This release adds encrypted runtime secrets, secret-backed authenticated API
calls, OpenClaw and Hermes Agent migration commands, and expanded local-model
setup with `llama.cpp` and local-only onboarding paths.
Release notes live in [CHANGELOG.md](./CHANGELOG.md), and the browsable
operator and maintainer manual lives under
[docs/development/README.md](./docs/development/README.md).

## HybridAI Advantage

- Security-focused foundation
- Enterprise-ready stack
- EU-stack compatibility
- GDPR-aligned posture
- RAG-powered retrieval
- Document-grounded responses

## Architecture

- **Gateway service** (Node.js) — shared message/command handlers, SQLite persistence (KV + semantic + knowledge graph + canonical sessions + usage events), scheduler, heartbeat, web/API, and channel integrations for Discord, Microsoft Teams, iMessage, WhatsApp, and email
- **TUI client** — thin client over HTTP (`/api/chat`, `/api/command`) with
  a structured startup banner that surfaces model, sandbox, gateway, and
  chatbot context before the first prompt
- **Container** (Docker, ephemeral) — HybridAI API client, sandboxed tool executor, and preinstalled browser automation runtime with cursor-aware snapshots for JS-heavy custom UI
- Communication via file-based IPC (input.json / output.json)

## Quick start

```bash
# Install dependencies
npm install

# Run onboarding (also auto-runs on first `gateway`/`tui` start if required runtime setup is missing)
hybridclaw onboarding

# Onboarding flow:
# 1) explicitly accept TRUST_MODEL.md (required)
# 2) choose HybridAI auth or a local-only setup
# 3) for HybridAI, create/login in the browser and paste the API key back into the CLI
# 4) for local-only setups, skip remote auth and configure Ollama, LM Studio, llama.cpp, or vLLM
# 5) choose the default bot/model and persist config + encrypted secrets under ~/.hybridclaw/

# Start gateway backend (default)
hybridclaw gateway

# Or run gateway in foreground in this terminal
hybridclaw gateway start --foreground

# For stdio MCP servers that rely on host tools like `docker` or `npx`
hybridclaw gateway start --foreground --sandbox=host

# If msteams.enabled=true and MSTEAMS_APP_PASSWORD is configured, gateway auto-connects to Microsoft Teams.
# If DISCORD_TOKEN is set, gateway auto-connects to Discord.
# If imessage.enabled=true, gateway auto-connects to iMessage using the configured backend.
# If email.enabled=true and EMAIL_PASSWORD is configured, gateway auto-connects to Email.
# If linked WhatsApp auth exists, gateway auto-connects to WhatsApp.

# Start terminal adapter (optional, in a second terminal)
hybridclaw tui

# Web chat UI (built into gateway)
# open http://127.0.0.1:9090/chat

# Agent and session dashboard
# open http://127.0.0.1:9090/agents

# Embedded admin console
# open http://127.0.0.1:9090/admin
# Browser terminal page
# open http://127.0.0.1:9090/admin/terminal
# Includes Dashboard, Terminal, Gateway, Sessions, Jobs, Bindings, Models, Scheduler, MCP, Audit, Skills, Plugins, Tools, and Config
# If WEB_API_TOKEN is unset, localhost access opens without a login prompt
# If WEB_API_TOKEN is set, /chat, /agents, and /admin all prompt for the same token
```

## Authentication

HybridClaw uses a unified provider setup surface:

```bash
hybridclaw auth login hybridai --browser
hybridclaw auth login hybridai --base-url http://localhost:5000
hybridclaw auth login codex --import
hybridclaw auth login openrouter anthropic/claude-sonnet-4 --api-key sk-or-...
hybridclaw auth login mistral mistral-large-latest --api-key mistral_...
hybridclaw auth login huggingface meta-llama/Llama-3.1-8B-Instruct --api-key hf_...
hybridclaw auth login local lmstudio --base-url http://127.0.0.1:1234
hybridclaw auth login local ollama llama3.2
hybridclaw auth login msteams --app-id 00000000-0000-0000-0000-000000000000 --tenant-id 11111111-1111-1111-1111-111111111111 --app-password secret
hybridclaw auth status hybridai
hybridclaw auth status codex
hybridclaw auth status openrouter
hybridclaw auth status mistral
hybridclaw auth status huggingface
hybridclaw auth status local
hybridclaw auth status msteams
hybridclaw auth logout hybridai
hybridclaw auth logout codex
hybridclaw auth logout openrouter
hybridclaw auth logout mistral
hybridclaw auth logout huggingface
hybridclaw auth logout local
hybridclaw auth logout msteams
hybridclaw auth whatsapp reset
```

Legacy 

[truncated…]