🤖 HandClaw

💡 HandClaw connects directly to OpenCode, which offers generous free quota with high-performance free models (Minimax M2.5 or GLM 5).

Install (Node ≥22)

npm install -g handclaw@latest
# or: pnpm add -g handclaw@latest

handclaw onboard --install-daemon

💡 Choose "Extra Quick Start" for a no-pain HandClaw installation. Note: You must install Claude Code / Codex / OpenCode yourself separately.

✨ What is handclaw?

Connect AI coding agents (Claude Code, Codex, OpenCode) to Slack, WhatsApp, Discord, Telegram, or Feishu. Each channel uses one CLI, different channels can use different ones.

• One workspace, multiple agents
• Multi-round conversations
• Switch agent by renaming channel

HandClaw: Remind you when work finished!

• One workspace = Multiple agents
• Code from phone, even from your watch
• Walk away, let agents work

⚖️ HandClaw vs OpenClaw ACP

HandClaw advantages:

1. Notifies users when coding tasks are completed
2. Supports persistent plan/build mode switching
3. Can stop running code CLI early with !stop
4. Manages projects via channel naming — just rename the channel to switch agents
5. No need to install acpx or complex configuration — it just works

My Story

Me Previously — Stuck at Desk

• Multiple monitors (5+ windows)
• Claude Code, Codex, OpenCode — all open at once
• Tethered to laptop, can't leave desk
• Every task needs me sitting in front of the computer

📖 How to Use

📱 Mobile-First Development

Work anywhere. From your phone, tablet, or any device with Slack. Your coding agents are always accessible.

⚡ Thinking Process

The thinking process is streamed to the user.

📂 One Channel = One Agent = One Project

Pattern: #l0-agent-repo_name (prefix l0/l1/l2 is optional)

• l0/l1/l2 — Autonomous level prefix (optional)
• agent — Coding agent: claude, codex, opencode
• repo_name — Your project repository name

#l0-claude-myapp   → Level 0 (80% need user agreement)
#l1-opencode-api   → Level 1 (moderate autonomy)
#l2-codex-prod    → Level 2 (fully autonomous)
#claude-myapp     → (no prefix, default)

Important Commands:

• !code <repo> — Set working repository (searches $WORKSPACE/repo_name, use if channel name doesn't follow pattern)
• !code switch plan — Persistently change to plan mode
• !code switch build — Persistently change to build mode
• !code model <model> — Persistently change the model
• !plan — One-time plan request
• !build — One-time build request
• !stop — Stop the running code CLI immediately

🔀 Migration & Status

Just rename the channel to switch agent and autonomous level!

#l1-opencode-repo1 → #l0-claude-repo1

📊 Status Commands

• !rate — Check autonomous level and your acceptance rate
• @OpenClawApp status — Summarize all channels' progress

🔄 Plan ↔ Build Mode

• !plan — One-time plan request
• !build — One-time build request

📸 Demo

Live Demo: [Add your demo URL here]

🛠️ Build From Source

# Clone and install dependencies
git clone https://github.com/deciding/handclaw.git
cd handclaw
git submodule update --init --recursive
cd openclaw

# Install and build
pnpm install
pnpm ui:build
pnpm build

# Set up Slack connection and install daemon
pnpm handclaw onboard --install-daemon

Slack Configuration

See SLACK_INSTALL.md for setup instructions.

Set these in your Slack config:

{
  "requireMention": false,
  "groupPolicy": "open",
  "streaming": "block"
}

• requireMention: false — Respond to any message in the channel
• groupPolicy: open — Allow any channel to use handclaw
• streaming: block — Wait for complete response before sending

WhatsApp Configuration

{
  "groups": {
    "120363407410666666@g.us": { // group ID (use handclaw logs --follow, send a message in group to get)
      "requireMention": false
    }
  },
  "groupPolicy": "allowlist",
  "groupAllowFrom": ["phone-number"]
}

Telegram Configuration

{
  "enabled": true,
  "dmPolicy": "pairing",
  "botToken": "YOUR_BOT_TOKEN",
  "groups": {
    "-5128902136": { // group ID
      "requireMention": false,
      "enabled": true
    }
  },
  "groupAllowFrom": [],
  "groupPolicy": "allowlist",
  "streaming": "block"
}

Discord Configuration

{
  "enabled": true,
  "token": "YOUR_DISCORD_TOKEN",
  "groupPolicy": "open",
  "streaming": "off",
  "guilds": {
    "1480825735710118119": { // guild ID
      "channels": {
        "*": { // channel ID
          "requireMention": false
        }
      }
    }
  }
}

How to Get IDs

• Telegram: @BotFather to create bot, @myidbot /getid for user ID, /getgroupid@myidbot in group for group ID
• Discord: Channel link contains guild ID and channel ID: https://discord.com/channels/{guild_id}/{channel_id}

Requirements

• Node.js 22+
• pnpm
• Slack workspace
• Install your own coding agents: Claude Code, Codex, and/or OpenCode

⚠️ Note: You must install Claude Code, Codex, or OpenCode separately. handclaw connects to them but doesn't include them.

💬 Join Community

📖 Documentation

• Getting Started
• Slack Setup
• Agent Configuration
• Channel Management

🤝 Contributing

PRs welcome! This is a fork of OpenClaw — the amazing whale project that makes all this possible.

📜 License

MIT

🐋 Built on OpenClaw

handclaw is a personal fork of OpenClaw — the open-source personal AI assistant framework. OpenClaw connects to 15+ messaging channels and supports multiple AI providers.

Check out the main project: github.com/openclaw/openclaw