🦅 HyperClaw

Your personal AI assistant — running on your hardware, talking on your channels.

One command to install. Works on Telegram, Discord, WhatsApp, Signal, iMessage and 25+ more.

📚 Docs · 📜 Commands Reference · 🏗 Architecture · ⚙️ Config · 🔒 Security · 🐳 Sandboxing · 🌊 Tlon · 💬 Google Chat · 🤝 Contributing

"One npm install -g hyperclaw and your AI is live on Telegram."

HyperClaw runs locally on your machine — your data, your keys, your control.

hyperclaw

hyperclaw osint
hyperclaw osint setup    # interactive session setup
hyperclaw osint --show   # show current profile

Passive recon · Bug bounty · Pentest · Digital footprint — all from your terminal.
For authorized security research only. Always have written permission.

Requires Node ≥ 22. Runs natively on Windows, macOS, and Linux — no WSL2 required.

# Install
npm install -g hyperclaw@latest

# Run the interactive setup wizard
hyperclaw onboard
# Run the interactive setup wizard with deamon
hyperclaw onboard --install-daemon

The wizard walks you through: AI provider → model → channels → skills. Done.

# Step 1 — Start the daemon (runs in the background, bot becomes active on Telegram/Discord/etc.)
hyperclaw daemon start

# Step 2 — Open the Dashboard to see live status, channels, logs
hyperclaw dashboard

# Step 3 — Or chat directly from your terminal (no Telegram needed)
hyperclaw chat

hyperclaw daemon start
        ↓
   Gateway  (background process)
        ↓
   ┌─────────────┬──────────────┐
   │  Telegram   │  Dashboard   │
   │  Discord    │  hyperclaw   │
   │  WhatsApp   │  dashboard   │
   └─────────────┴──────────────┘

The daemon must be running for the Telegram/Discord/WhatsApp bot to answer messages and for the Dashboard to show "Running".
On Windows the daemon runs via Task Scheduler (no WSL, no admin).
On Linux/macOS with --install-daemon it uses systemd / launchd.

If you haven't installed the daemon, run the bot in the foreground — the terminal stays open:

# Run bot in foreground (Ctrl+C to stop)
hyperclaw start

# In a second terminal, open the dashboard
hyperclaw dashboard

# Send a single message (non-interactive)
hyperclaw agent --message "What can you do?"

Windows: No WSL2, no admin rights needed. The daemon uses Task Scheduler and runs as your account.

Linux: If you get an EACCES: permission denied error during npm install -g, see the Linux install fix below.

Emojis not showing? See the Terminal emoji fix below.

# pnpm
pnpm add -g hyperclaw@latest

# Install with daemon (auto-start on boot + full PC access)
hyperclaw onboard --install-daemon

# Uninstall
hyperclaw daemon uninstall
npm uninstall -g hyperclaw
rm -rf ~/.hyperclaw   # optional — removes config and data

# 1. Create a user-owned npm directory
mkdir -p ~/.npm-global

# 2. Tell npm to use it
npm config set prefix '~/.npm-global'

# 3. Add it to your PATH
#    bash users:
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc && source ~/.bashrc
#    zsh users (macOS default, Kali zsh, etc.):
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc && source ~/.zshrc
#    fish users:
echo 'set -x PATH ~/.npm-global/bin $PATH' >> ~/.config/fish/config.fish

# 4. Install (no sudo needed)
npm install -g hyperclaw@latest

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc   # or ~/.zshrc

# Install Node 22
nvm install 22
nvm use 22

# Install HyperClaw (no sudo, no prefix config needed)
npm install -g hyperclaw@latest

sudo npm install -g hyperclaw@latest

# Debian / Ubuntu / Kali
sudo apt install fonts-noto-color-emoji

# Arch / Manjaro
sudo pacman -S noto-fonts-emoji

# Fedora / RHEL
sudo dnf install google-noto-emoji-fonts

brew install --cask iterm2

HyperClaw connects to the channels you already use (28+ channels):

Twitch is also available via IRC over WebSocket.

Add a channel:

hyperclaw channels add telegram

WhatsApp / Telegram / Slack / Discord / Signal / iMessage
Google Chat / Matrix / IRC / Mattermost / Teams / Nostr / WebChat
               │
               ▼
┌──────────────────────────────────┐
│           HyperClaw Gateway      │
│        ws://127.0.0.1:18789      │
│  sessions · auth · routing       │
│  tools · cron · webhooks         │
└──────────────┬───────────────────┘
               │
       ┌───────┼───────┐
       ▼       ▼       ▼
   Agent     CLI     Nodes
  (Claude,  (hyperclaw  (macOS/iOS/
  OpenRouter  …)       Android)
  OpenAI…)

HyperClaw supports 20+ providers. Pick one in the wizard or set provider.providerId in config:

Minimal ~/.hyperclaw/hyperclaw.json:

{
  "provider": {
    "providerId": "anthropic",
    "modelId": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  },
  "gateway": {
    "port": 18789
  }
}

Or use OpenRouter (access to all models with one key):

{
  "provider": {
    "providerId": "openrouter",
    "modelId": "anthropic/claude-opus-4-6",
    "apiKey": "sk-or-..."
  }
}

Full reference: docs/configuration.md

The gateway watches ~/.hyperclaw/hyperclaw.json and applies changes automatically — no restart needed for most settings:

{
  "gateway": {
    "reload": { "mode": "hybrid", "debounceMs": 300 }
  }
}

If you run behind Nginx, Caddy, or Cloudflare Tunnel, set trustedProxies so the gateway resolves the real client IP from X-Forwarded-For:

{
  "gateway": {
    "trustedProxies": ["127.0.0.1", "10.0.0.0/8"]
  }
}

Isolate DM sessions per channel/peer (useful when multiple people share one gateway):

{
  "session": { "dmScope": "per-channel-peer" }
}

HyperClaw connects to real messaging surfaces. Inbound DMs are treated as untrusted input.

Default behavior:

• dmPolicy: "pairing" — unknown senders get a pairing code, message is not processed. Approve with: hyperclaw pairing approve telegram <CODE>
• Set dmPolicy: "open" only if you want anyone to reach your assistant.
• Non-main sessions (groups/channels) can run in Docker sandboxes: agents.defaults.sandbox.mode: "non-main"

Run the security audit regularly:

hyperclaw security audit           # standard scan
hyperclaw security audit --deep    # live gateway probe
hyperclaw security audit --fix     # auto-fix safe issues
hyperclaw security audit --json    # machine-readable output

Full guide: docs/security.md

• Local-first Gateway — single control plane for sessions, channels, tools, and events
• Config hot reload — gateway watches ~/.hyperclaw/hyperclaw.json, hot-applies changes (hybrid/hot/restart/off)
• Multi-channel inbox — 28+ channels, unified session model
• Multi-agent routing — route channels/accounts to isolated agent workspaces
• Extended thinking — Claude extended thinking with /think high in chat
• Voice — Talk Mode with ElevenLabs TTS + system TTS fallback
• Live Canvas — agent-driven visual workspace with A2UI protocol
• PC Access — bash, file read/write, screenshot, clipboard (opt-in, sandboxed)
• Tool policy — per-provider allow/deny lists and profiles (full, coding, messaging, minimal)
• Auto-memory — extracts facts from conversations automatically
• Skills — bundled and workspace skills (reminders, translator, web search, etc.)
• Daemon mode — launchd/systemd user service, auto-restart, 🩸 icon
• Update notifications — notifies when a newer version is available on npm (non-blocking check at startup)
• MCP support — Model Context Protocol server and client
• Docker — sandboxed agent execution, browser tools with Puppeteer
• Tailscale — Serve/Funnel for remote access without port forwarding

The Gateway alone delivers a great experience. Apps add extra features:

• Menu bar control + health indicator
• Voice Wake + Push-to-Talk overlay
• WebChat + debug tools
• Remote gateway control

• Pairs over Gateway WebSocket (Bonjour discovery + manual)
• Canvas surface + Voice
• Camera and screen capture tools

• Connect/Chat/Voice tabs + Canvas
• Camera, screen capture, device commands
• Notifications, contacts, calendar, photos

Three release channels, switch any time:

hyperclaw update --channel stable   # tagged releases (default)
hyperclaw update --channel beta     # prereleases
hyperclaw update --channel dev      # moving head of main

The agent has built-in tools for common integrations — no extra packages needed. Full reference: docs/integrations.md

Example — ask the agent:

"What's the weather in Athens for the next 3 days?"
"Generate an image of a space lobster"
"Play some Daft Punk on Spotify"
"Turn on the living room lights"      # Home Assistant or Philips Hue
"List my open GitHub issues"
"Add 'Buy milk' to my Reminders"
"Create a note in Obsidian: Meeting notes..."
"Add a card to my Trello board"
"Set my 8Sleep to temperature 20 on the left side"

"Get my GitHub password from 1Password"
"Send an iMessage to +1234567890: I'll be late"
"What's playing on my Sonos?"

Option 1 — During onboarding wizard (recommended for first setup):

hyperclaw onboard
# At the end of the wizard, you'll be asked:
# "Configure integrations now? (Spotify, Home Assistant, GitHub, Trello, etc.)"
# Select the ones you want and enter your keys interactively.

Option 2 — Tell the agent (easiest after setup):

You › Save my Spotify keys:
      CLIENT_ID: abc123
      CLIENT_SECRET: xyz456
      REFRESH_TOKEN: def789

Option 3 — CLI command:

hyperclaw config set-key SPOTIFY_CLIENT_ID abc123
hyperclaw config set-key SPOTIFY_CLIENT_SECRET xyz456
hyperclaw config set-key GITHUB_TOKEN ghp_xxxx
hyperclaw config set-key HA_URL http://homeassistant.local:8123
hyperclaw config set-key HA_TOKEN your-long-lived-token

Option 4 — Edit directly ~/.hyperclaw/.env:

SPOTIFY_CLIENT_ID=abc123
SPOTIFY_CLIENT_SECRET=xyz456
GITHUB_TOKEN=ghp_xxxx
HA_URL=http://homeassistant.local:8123
HA_TOKEN=your-token
TRELLO_API_KEY=abc
TRELLO_TOKEN=xyz
OBSIDIAN_API_KEY=abc
HUE_BRIDGE_IP=192.168.1.100
HUE_USERNAME=your-username
SONOS_IP=192.168.1.50
GIPHY_API_KEY=abc
OP_SERVICE_ACCOUNT_TOKEN=ops_xxxx

All keys are stored locally in ~/.hyperclaw/.env — never sent anywhere except the respective service.

When the gateway is running, the agent can communicate with other connected sessions:

Example — ask the agent:

"List all connected sessions and send a briefing to the first one"

Interactive multi-turn chat with the agent directly from your terminal:

hyperclaw chat                          # start a session
hyperclaw chat --thinking high          # enable extended thinking
hyperclaw chat --session my-session     # named session
hyperclaw chat --model claude-opus-4-6  # override model

Responses stream token-by-token as they are generated. The full conversation history is kept for the entire session (true multi-turn context).

Send these in any connected channel (Telegram, Discord, Slack, etc.):

SkillHub is HyperClaw's skill registry. Full guide: docs/skillhub.md

The agent can install skills on demand or you can install them via the wizard:

# Install a skill
hyperclaw skills install web-search

# List installed skills
hyperclaw skills list

Featured skills: web-search · file-manager · code-runner · github-tools · calendar-tools · summarizer

Option 1 — tell the agent (easiest):

You › Install the web-search skill
You › Install this: https://clawhub.ai/user/skill-name

The agent automatically calls install_skill_from_hub — no commands needed.

Option 2 — /skills inside hyperclaw chat:

You › /skills

Shows installed skills and how to add more:

  Installed skills:
  • Web Search      (web-search)
  • File Manager    (file-manager)

  How to add a skill:
  1. Tell the agent:  "Install the web-search skill"
  2. Paste a link:    "Install this: https://clawhub.ai/user/skill-name"
  3. CLI:             hyperclaw skill install <name>
  4. Re-run wizard:   hyperclaw onboard

/skills also appears in /help and in the chat header when you open hyperclaw chat.

Option 3 — CLI:

hyperclaw skill install web-search
hyperclaw skills list

Give the agent a clawhub.ai link and it installs automatically:

"Install this skill: https://clawhub.ai/b0tresch/stealth-browser"

The agent calls install_skill_from_hub — fetches SKILL.md + extra files, writes them to ~/.hyperclaw/workspace/skills/, and runs npm install if needed.

The agent can create fully custom skills on demand:

"Create a skill that summarizes my daily Telegram messages"

create_skill supports:

• content — SKILL.md instructions
• files — JSON map of extra files (e.g. {"scripts/run.js": "..."})
• npmInstall: "true" — auto-runs npm install after writing files

Skills are saved to ~/.hyperclaw/workspace/skills/{id}/ and loaded on the next message.

Control the gateway remotely via your Telegram or Discord bot (hyperclaw bot start):

git clone https://github.com/mylo-2001/hyperclaw.git
cd hyperclaw

pnpm install
pnpm build

# Run onboarding
node dist/run-main.js onboard

# Dev loop (auto-reload)
npm run gateway:watch

# Build
docker build -t hyperclaw .

# Run (mounts your config dir)
docker run -p 18789:18789 \
  -v ~/.hyperclaw:/data/hyperclaw \
  hyperclaw

Sandbox image (no PC access, restricted tools):

docker build -f Dockerfile.sandbox -t hyperclaw:sandbox .

Or use Docker Compose for the full stack (gateway + browser sandbox):

# Copy and fill in your API keys
cp env.example .env

# Start gateway + sandbox
docker compose --profile full up -d

See docker-compose.yml and env.example for all options.

hyperclaw/
├── src/                    # Core CLI, gateway, channels, tools
│   ├── cli/                # CLI entry point + onboarding wizard
│   ├── gateway/            # Gateway server + manager (re-exports)
│   ├── channels/           # Channel connectors + registry
│   ├── services/           # MCP, memory, heartbeat, cron
│   ├── agent/              # Agent loop, orchestrator, tool dispatch
│   ├── canvas/             # A2UI Canvas renderer
│   ├── commands/           # CLI sub-commands (channels, pairing…)
│   ├── hooks/              # Lifecycle hooks (boot, cron, memory)
│   ├── infra/              # Tool policy, destructive gate, secrets
│   ├── media/              # Voice, TTS, STT, audio
│   ├── routing/            # Session routing + multi-agent dispatch
│   ├── security/           # Auth, sandboxing, DM policy
│   └── …                   # (sdk, types, webhooks, logging, plugins…)
├── packages/
│   ├── core/               # Inference engine, agent loop
│   ├── gateway/            # Gateway package (standalone)
│   └── shared/             # Shared types + path utilities
├── apps/
│   ├── ios/                # iOS node app
│   ├── android/            # Android node app
│   ├── macos/              # macOS menu bar app
│   ├── macos-menubar/      # Tauri macOS menu bar
│   └── web/                # Web UI (React + Vite)
├── extensions/             # Channel connectors (Telegram, Discord…)
├── skills/                 # Bundled skills (reminders, translator)
├── workspace-templates/    # Agent config templates (AGENTS.md, SOUL.md, TOOLS.md…)
├── scripts/                # Build + utility scripts
├── tests/                  # Vitest — unit / integration / e2e
└── docs/                   # Full documentation

See ROADMAP.md for the full plan.

Full history in CHANGELOG.md.

See CONTRIBUTING.md for guidelines. AI/vibe-coded PRs welcome!

Found a bug? Open an issue.
Found a vulnerability? Email [email protected] — we respond within 48 h.

MIT — see LICENSE.

Inspired by openclaw/openclaw.