HaoClaw

A personal assistant built on a powerful coding agent core.

Prerequisites

• Bun >= 1.3
• An Anthropic API key

Quick Start

# Clone and install
git clone https://github.com/zhisbug/haoclaw.git
cd haoclaw
bun install

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

# Start the gateway server (Terminal 1)
bun run gateway

# Start the TUI client (Terminal 2)
bun run dev

Architecture

HaoClaw uses a gateway-client architecture. The gateway is a long-lived process that manages the agent, sessions, memory, and skills. The TUI is a thin client that connects via WebSocket.

┌─────────────────────────────────────────┐
│  GATEWAY (bun run gateway)              │
│  Manages: agent, sessions, memory,      │
│  skills, workspace, heartbeat, cron     │
│  Serves: HTTP health + WebSocket RPC    │
└──────────────┬──────────────────────────┘
               │ ws://localhost:4242
     ┌─────────┼─────────┐
     │         │         │
  ┌──┴──┐  ┌──┴──┐  ┌───┴───┐
  │ TUI │  │ Web │  │Mobile │
  │(Ink)│  │(PWA)│  │(PWA)  │
  └─────┘  └─────┘  └───────┘
  All clients are thin UI layers.

Why this design?

• One agent process serves all clients (TUI, web, mobile)
• Background services (heartbeat, cron) run in the gateway
• Sessions persist across client restarts
• Same permission UX across all clients

Usage

Gateway Server

The gateway must be running before starting any client.

# Start gateway (foreground, with console logs)
bun run gateway

# Gateway with a specific model
bun run gateway -- --model claude-opus-4-6

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

The gateway initializes workspace, memory, skills, and listens on ws://localhost:4242.

TUI Client

# Connect to local gateway (default: ws://localhost:4242)
bun run dev

# Connect to remote gateway
bun run dev -- --connect ws://remote-host:4242

# Use a specific session (default: tui:main)
bun run dev -- --session my-project

# Show help
bun run dev -- --help

TUI Controls

| Key | Action | |-----|--------| | Enter | Send message | | Ctrl+J | New line (multi-line input) | | Esc | Cancel current agent turn | | Ctrl+C | Exit TUI | | Ctrl+D | Toggle task viewer |

Slash Commands

| Command | Description | |---------|-------------| | /help | Show all commands | | /new | Start fresh session | | /model <name> | Show or switch model | | /status | Show session info | | /history | Show token usage | | /skills | List available skills | | /compact | Summarize old messages to free context space | | /mcp | Show connected MCP servers and tools | | /flush | Extract durable memories to daily log | | /exit | Exit TUI |

File Reading

The read_file tool supports multiple file formats:

| Format | What happens | |--------|-------------| | Text (.ts, .py, .md, etc.) | Line-numbered output, offset/limit for ranges | | Images (.png, .jpg, .gif, .webp) | Sent as visual content — the model sees the image via its vision capability | | PDFs (.pdf) | Text extraction with pages parameter for ranges (e.g., "1-5") | | Jupyter notebooks (.ipynb) | Formatted cells with code, outputs, and error tracebacks | | SVG | Returned as text for editing |

Note: Image and file attachments (drag-and-drop into input) are planned but not yet implemented. Currently, the agent reads files from disk via the read_file tool.

MCP Integration

HaoClaw supports the Model Context Protocol for extending the agent with external tool servers.

{
  "mcp_servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "permission": "auto_approve"
    }
  }
}

Add MCP servers to ~/.haoclaw/config.json, restart the gateway. The agent discovers tools automatically and can use them in conversation. Use /mcp to check server status.

Configuration

Config file: ~/.haoclaw/config.json (created on first run)

{
  "api_keys": {
    "anthropic": "sk-ant-...",
    "openai": "",
    "brave_search": ""
  },
  "model": "claude-sonnet-4-6",
  "gateway_port": 4242
}

Environment variables override config:

• ANTHROPIC_API_KEY — Anthropic API key (required)
• OPENAI_API_KEY — For semantic memory search (optional)
• BRAVE_API_KEY — For web search (optional)
• HAOCLAW_LOG_LEVEL — Log level: silent/fatal/error/warn/info/debug/trace
• HAOCLAW_DEBUG — Debug flags: gateway/*, agent/loop, etc.

Development

# Type check
bun run typecheck

# Unit + integration tests (no API keys needed)
bun run test

# E2E tests (requires API keys)
ANTHROPIC_API_KEY=sk-ant-... BRAVE_API_KEY=... bun run test:e2e

# All tests
ANTHROPIC_API_KEY=sk-ant-... BRAVE_API_KEY=... bun run test:all

Test Structure

| Command | Tests | What | |---------|-------|------| | bun run test | ~1720 | Unit tests with mocks | | bun run test:integration | 55 | Integration tests | | bun run web:test | 166 | Web UI component tests (vitest) | | bun run test:e2e | 5 files | Real API calls + gateway E2E (needs keys) |

Manual Tests

See tests/MANUAL_TESTS.md for the interactive testing checklist.

Project Structure

src/
├── index.ts              # CLI entry point (chat client + gateway server)
├── agent/                # Agent core (loop, context, streaming, types)
├── tools/                # Built-in tools (bash, file ops, web, memory)
├── gateway/              # Gateway server + client
│   ├── server.ts         # Bun.serve() HTTP + WebSocket
│   ├── protocol.ts       # JSON-RPC frame types
│   ├── connection.ts     # WebSocket connection management
│   ├── command-queue.ts  # Lane-based concurrency control
│   ├── agent-sessions.ts # Per-session agent loop management
│   ├── gateway-client.ts # WebSocket client (used by TUI)
│   └── ws-permission.ts  # Permission flow over WebSocket
├── tui/                  # Terminal UI (Ink/React)
│   ├── app.tsx           # Root component
│   ├── components/       # UI components
│   └── hooks/            # React hooks (agent event subscription)
├── mcp/                  # MCP client (server manager, tool bridge)
├── storage/              # Config, sessions, workspace
├── memory/               # Hybrid BM25 + vector search
├── skills/               # Skill system (SKILL.md files)
├── logging/              # Structured logger (subsystem-tagged)
└── skill-templates/      # 8 bundled skills

Documentation

• ARCHITECTURE.md — Full technical architecture
• tests/MANUAL_TESTS.md — Manual testing checklist