Skip to content

README.md

Latest commit

 

History

History
327 lines (238 loc) · 8.14 KB

README.md

File metadata and controls

327 lines (238 loc) · 8.14 KB

🤖 HandClaw

HandClaw

One HandClaw — Many Projects

You don't need many openclaws. You just need one to control all.
(Slack, WhatsApp, Discord, Telegram, Feishu)

💡 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

Extra Quick Start

💡 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.

Overview

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

HandClaw: Remind you when work finished!

HandClaw on Phone HandClaw on Watch

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

⚖️ HandClaw vs OpenClaw ACP

Feature HandClaw OpenClaw ACP
Notify when task complete ✅ Yes ❌ No
Switch plan/build mode ✅ Yes (!code switch plan/build) ❌ No
Early stop code CLI ✅ Yes (!stop) ❌ No
Project management via channels ✅ Just rename channel ❌ Need install acpx + complex config
Support ACP ✅ Easy (rename channel) ❌ Complex (install acpx, configure)

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

Busy without handclaw

  • 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!

Channel Naming
Channel Naming
l0-claude-repo1 		Migration
Migration
Rename to switch 		Status
Status
`@BotApp status` to check 
#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

HandClaw Desktop 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

Platform Link
Discord Join Discord
WeChat WeChat

📖 Documentation

🤝 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

Try it now →