HyperClaw

Your personal AI that actually gets things done.

HyperClaw is a personal AI assistant that works across your entire life. Not just chat — it connects to your email, calendar, tasks, documents, and more. It remembers everything, learns your preferences, and coordinates 44 specialized AI agents to help you with anything.

What's New in v0.2.0

• Claude 5 family with tiered model routing (sonnet-5 / opus-5 / fable-5) and automatic failover — overloads degrade gracefully instead of going silent
• Universal file delivery — the send_file tool pushes any document, deck, spreadsheet, image, or video into the conversation you're already in (Telegram documents, iMessage attachments, email attachments) or opens it on the Mac
• Full email suite — HTML email, in-thread replies, forwarding with attachments, drafts-as-approval, archive/star/read, Gmail search
• Offsite heartbeat — a dead-man's-switch template that alerts you externally if the machine running your assistant dies (see .env.example → HEARTBEAT_URL)
• Persona templating — your assistant's identity lives in an untracked file (persona.example.md), not in source code
• Hardened channel security — fail-closed allowlists for iMessage and Telegram; see SECURITY.md before exposing the bot to any channel

What Can It Do?

• Manage your communications — Email, Telegram, Slack, Discord, WhatsApp, Teams
• Organize your work — Calendar, tasks, projects, documents
• Handle your data — Notion, Airtable, Google Sheets, Salesforce, HubSpot
• Support your business — Invoicing, customer tracking, sales pipelines
• Research anything — Web search, document analysis, data synthesis
• Remember everything — Your preferences, history, context across all sessions
• Optimize costs — Smart model routing uses cheap models for simple tasks

One AI. Every platform. All working together.

Architecture

Cost-Optimized Model Router

HyperClaw intelligently routes tasks to the most cost-effective model:

Simple "what time is it?" stays cheap. "Refactor this system end to end" gets Fable 5 — and if a model is overloaded, the failover chain walks down the ladder instead of dropping your request.

Multi-Agent Coordination

44 specialized agents organized by domain:

• Business (11): Strategos, Herald, Pipeline, Ledger, Counsel, Talent, Nexus, Ops, Revenue, Sovereign, Venture
• Personal (6): Atlas, Midas, Vitals, Nourish, Navigator, Hearth
• Scientific (5): Medicus, Cosmos, Gaia, Oracle, Scribe
• Communications (5): Echo, Envoy, Pulse, Cipher, Herald
• Talent (4): Scout, Deal, Stage, Roster
• Trading (3): Prediction Strategist, Polymarket Trader, Global Prediction Engine
• Technology (3): Aegis, Bridge, Forge
• Recursive (3): Scout, Alchemist, Calibrator
• Intelligence (2): Sentinel, Arbiter
• Creative (2): Author, Lens

Tasks are automatically routed to the best agent based on domain and complexity.

Persistent Memory

Memory persists across sessions:

• Working Memory — Current context and active tasks
• Episodic Memory — Conversation history and decisions
• Semantic Memory — Facts and knowledge
• Instincts — Learned behavioral patterns

Getting Started

Option 1: Quick Start (5 minutes)

macOS:

brew install pipx
pipx install hyperagents       # the command is still `hyperclaw`
hyperclaw init

Linux/Windows:

pip install hyperagents
hyperclaw init

The init command runs an interactive setup that will:

1. Ask for your name and what to call your AI
2. Guide you through API key setup (Anthropic)
3. Optionally set up database for persistent memory
4. Launch the chat interface

Then use interactive chat:

hyperclaw start

Or run the TUI:

hyperclaw-tui

Option 2: Self-Host with Docker

# Clone the repo
git clone https://gitlab.com/hyper-nimbus-group/hyperclaw.git
cd hyperclaw

# Copy the example config
cp .env.example .env

# Edit .env and add your Anthropic API key
# ANTHROPIC_API_KEY=sk-ant-your-key

# Optional: Add ChatJimmy for cheap simple tasks
# CHATJIMMY_API_KEY=your-taalas-key

# Start
docker-compose up

Open http://localhost:8001 in your browser.

Option 3: Production Setup

# Clone and setup
git clone https://gitlab.com/hyper-nimbus-group/hyperclaw.git
cd hyperclaw
pip install -r requirements.txt

# Initialize workspace and config
python -m hyperclaw setup

# Initialize database (requires DATABASE_URL in .env)
python -m hyperclaw setup --init-db

# Start server
python -m hyperclaw server --port 8001

Configuration

Required

• ANTHROPIC_API_KEY — Powers the AI brain
  • Get one at console.anthropic.com

Recommended

• DATABASE_URL — PostgreSQL with pgvector for memory

  • Easiest: Supabase (free tier works)
  • Run schema/init.sql to create tables

• CHATJIMMY_API_KEY — Cheap model for simple tasks

  • Get one at taalas.ai
  • Reduces costs by 90%+ for simple queries

Optional Integrations

Messaging:

TELEGRAM_BOT_TOKEN=your-bot-token
SLACK_BOT_TOKEN=xoxb-your-token

Telegram polling and the scheduled jobs (heartbeat, morning brief, nightly memory consolidation) are off by default. They start only with HYPERCLAW_UNATTENDED=1; see docs/UNATTENDED-MODE.md.

Email:

GMAIL_CLIENT_ID=...
GMAIL_CLIENT_SECRET=...
GMAIL_REFRESH_TOKEN=...

See .env.example for all available integrations.

API Endpoints

Chat

# Simple chat
curl -X POST http://localhost:8001/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What can you help me with?"}'

# Streaming chat
curl -X POST http://localhost:8001/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Explain quantum computing", "stream": true}'

Tasks

# Create a task
curl -X POST http://localhost:8001/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"goal": "Research competitors in AI space", "domain": "business"}'

# Get task status
curl http://localhost:8001/api/tasks/abc123

# List all tasks
curl http://localhost:8001/api/tasks

Multi-Agent Coordination

# Coordinate complex goal across multiple agents
curl -X POST http://localhost:8001/api/coordinate \
  -H "Content-Type: application/json" \
  -d '{"goal": "Create a complete marketing strategy for product launch"}'

Memory

# Store a memory
curl -X POST http://localhost:8001/api/memory/remember \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers concise responses", "importance": 0.8}'

# Recall memories
curl -X POST http://localhost:8001/api/memory/recall \
  -H "Content-Type: application/json" \
  -d '{"query": "user preferences"}'

Cost Management

# Get current costs
curl http://localhost:8001/api/costs

# Set daily budget
curl -X POST "http://localhost:8001/api/costs/budget?budget_usd=5.0"

# List available models
curl http://localhost:8001/api/models

System

# Health check
curl http://localhost:8001/health

# Full status
curl http://localhost:8001/status

# List agents
curl http://localhost:8001/api/agents

# List integrations
curl http://localhost:8001/api/integrations

CLI Commands

# Setup workspace and configuration
hyperclaw setup
hyperclaw setup --init-db  # Also initialize database

# Start the server
hyperclaw server
hyperclaw server --port 8080

# Interactive chat
hyperclaw chat

# Check status
hyperclaw status

# Memory operations
hyperclaw memory list
hyperclaw memory recall "user preferences"
hyperclaw memory remember "Important note"

# Version
hyperclaw version

Workspace Structure

After setup, HyperClaw creates:

~/.hyperclaw/
├── workspace/
│   ├── SOUL.md           # AI personality
│   ├── IDENTITY.md       # AI configuration
│   ├── USER.md           # Your profile
│   ├── MEMORY.md         # Working memory
│   └── secrets/
│       └── .env          # API keys
├── memory/
│   ├── instincts.md      # Learned behaviors
│   ├── core-episodes.md  # Key memories
│   └── daily/            # Daily logs
├── config/
│   └── hyperclaw.yaml    # System config
└── logs/

Edit these files to customize your assistant's behavior.

Cost Optimization Tips

1. Use ChatJimmy — Add CHATJIMMY_API_KEY to route simple tasks to a model that costs 100x less

2. Cost caps — every model call goes through the cost guard (hyperclaw/cost_guard.py). At the daily cap or the per-task cap HyperClaw stops (no further model calls, never a cheaper model) and asks you whether to continue, with what was done (from the activity log and tool results), what remains and the spend so far. Answers above a small amount end with a spend line. Scheduled jobs and guest chats stop and notify you only.

   • hyperclaw cost shows today's spend; hyperclaw cost raise --daily 20 / --task 5 (or /cost raise daily 20 in the terminal) changes a cap — your explicit action, recorded in hyperclaw activity.
   • Settings: config.json key cost_guard (daily_cap_usd, default 10; task_cap_usd, default 2; spend_line_min_usd, default 0.01; prices), else the environment (HYPERCLAW_DAILY_CAP_USD — legacy DAILY_BUDGET_USD — HYPERCLAW_TASK_CAP_USD, HYPERCLAW_SPEND_LINE_MIN_USD). Hyper deployments set them in config.json.
   • Prices are USD per 1k tokens: cost_guard.prices ({"<model>" or "provider:<name>": {"input_per_1k": …, "output_per_1k": …}}), then models.yaml cost_per_1k_*, then a built-in table. HyperSpeed V2 uses a placeholder rate until Hyper sets its internal rate as prices["provider:hyperspeed"]. An unknown model is charged a conservative rate, never 0. Spend is kept per day in $HYPERCLAW_ROOT/ledger/cost.sqlite3 (survives restarts).

3. Enable prefer_cheap — Set PREFER_CHEAP_MODELS=true to always prefer the cheapest capable model

4. Monitor usage — Check /api/costs to see spend by model

Database Setup (Optional but Recommended)

For persistent memory across sessions, set up PostgreSQL with pgvector:

1. Create a Supabase project (free) or use any PostgreSQL
2. Enable the vector extension
3. Run schema/init.sql to create tables
4. Add DATABASE_URL to your .env

# Initialize database
python -m hyperclaw setup --init-db

Privacy & Security

• Your data stays yours — Self-host means nothing leaves your machine
• No tracking — We don't collect anything
• Open source — Audit the code yourself
• Per-agent permissions — Control what each agent can access
• Channel allowlists — iMessage/Telegram deny strangers by default; read SECURITY.md before connecting any channel

Troubleshooting

For terminal authentication errors after a Hyperspeed outage, see provider recovery.

"API key not working"

• Make sure it starts with sk-ant-
• Check for extra spaces when pasting

"Database connection failed"

• Verify your DATABASE_URL is correct
• For Supabase, use the "Transaction pooler" connection string

"Integration not connecting"

• Run hyperclaw integrations test <name> to diagnose
• Check that API keys are in your .env file

Need help?

• Run hyperclaw status to check system health
• Open an issue on GitLab

Contributing

MIT licensed. Contributions welcome.

git clone https://gitlab.com/hyper-nimbus-group/hyperclaw.git
cd hyperclaw
pip install -e ".[dev]"
python -m pytest tests/ -v

See CONTRIBUTING.md for guidelines.

License

MIT — use it, modify it, build on it.