Open Coding Claw

Hierarchical multi-agent orchestration for OpenCode.

Open Coding Claw turns OpenCode into a coordinated engineering team:

• claw-master is orchestration-only and does not write code directly
• specialist subagents handle frontend, backend, research, review, computer use, and fast exploration
• subagents can send typed peer messages to each other without routing through the master
• LSP and AST toolkits are exposed as first-class capabilities
• built-in MCP baseline adds docs, research, and browser automation servers
• MCP tools are assigned by agent role instead of being shared equally across every agent
• computer use now includes cross-platform desktop tools for real mouse, keyboard, screenshots, window focus, app launch, and optional OCR
• computer use also includes an optional semantic accessibility layer for UI trees and element-level actions
• WhatsApp can be attached to a live session so messages from your own account behave like session prompts, with short start/finish replies

This project borrows the practical plugin architecture ideas from oh-my-openagent, while staying focused on a smaller, explicit OpenCode plugin surface.

Why This Exists

Most "multi-agent" coding setups still collapse into one big generalist agent with a few labels.

Open Coding Claw takes a stricter approach:

• the master agent coordinates and delegates
• implementation is pushed to specialist workers
• review is a separate concern
• computer use is isolated behind its own agent role
• WhatsApp is treated as an operator interface, not as the execution engine

The result is a cleaner control plane for long-running coding work.

Built-in Agents

Agent	Role	Default model
claw-master	Planning, delegation, aggregation, user-facing coordination	openai/gpt-5.4
frontend-agent	UI, visual implementation, frontend polish	anthropic/claude-sonnet-4.6
backend-agent	APIs, services, data flow, backend changes	openai/gpt-5.4
research-agent	Web-backed investigation and evidence gathering	openai/gpt-5.4
review-agent	Code review, regression detection, verification gaps	openai/gpt-5.4
computer-use-agent	Real desktop-style interaction workflows	openai/gpt-5.4
explore-agent	Cheap and fast repo exploration	openai/gpt-5.4-mini

Core Architecture

Open Coding Claw is organized into three layers:

1. claw-master Reads context, decides the execution shape, delegates tasks, and owns user-facing progress communication.
2. specialist subagents frontend-agent, backend-agent, research-agent, review-agent, computer-use-agent, and explore-agent.
3. shared runtime Agent registry, task router, execution policy, peer message bus, session store, WhatsApp bridge, and tool surface.

Design rules:

• claw-master should not code directly
• subagents may communicate laterally through the internal typed bus
• review is separated from implementation
• MCP access is role-scoped: research/review get docs and search, frontend gets docs plus browser automation, computer-use gets browser automation, explore stays light
• whole-computer control is exposed through dedicated claw_desktop_* tools and is distinct from browser-only Playwright automation
• WhatsApp notifications stay short and do not expose internal execution steps
• risky computer-use flows are expected to go through explicit safety checks

More detail: docs/architecture.md

WhatsApp Session Mode

Open Coding Claw includes a Baileys-based WhatsApp Web bridge inspired by the openclaw integration approach.

The current runtime model is session-scoped:

• WhatsApp receive is off by default
• new users can be paired per WhatsApp account through a QR-based pairing flow
• one WhatsApp account can be receive-enabled in only one OpenCode session at a time
• one session can bind multiple WhatsApp accounts
• multiple WhatsApp accounts can be stored and linked
• inbound WhatsApp messages are tagged as WhatsApp-originated before being injected into the session
• for WhatsApp-originated requests, the system sends short WhatsApp replies when work starts and when it finishes

Current short replies:

• start: a short Chinese acknowledgement that work has started
• blocked: a short Chinese request for more input
• complete: a short Chinese completion notice

Runtime Tools

These plugin tools are relevant for WhatsApp operations:

• claw_whatsapp_status
• claw_mcp_status
• claw_whatsapp_account_add
• claw_whatsapp_login
• claw_whatsapp_pairing_start
• claw_whatsapp_pairing_pending
• claw_whatsapp_pairing_approved
• claw_whatsapp_pairing_revoke
• claw_whatsapp_receive_on
• claw_whatsapp_receive_off
• claw_whatsapp_receive_bindings

Built-in session commands:

• /claw-whatsapp-accounts
• /claw-whatsapp-add-account <account-id>
• /claw-whatsapp-login <account-id>
• /claw-whatsapp-pair-user <account-id>
• /claw-whatsapp-bind-account <account-id>
• /claw-whatsapp-unbind-account [account-id]

Desktop-control tools for computer-use-agent:

• claw_desktop_status
• claw_desktop_snapshot
• claw_desktop_mouse_move
• claw_desktop_click
• claw_desktop_drag
• claw_desktop_scroll
• claw_desktop_type
• claw_desktop_press_keys
• claw_desktop_launch_app
• claw_desktop_open
• claw_desktop_windows
• claw_desktop_focus_window
• claw_desktop_ui_tree
• claw_desktop_find_element
• claw_desktop_click_element
• claw_desktop_type_into_element

Typical flow:

1. Open a normal OpenCode session.
2. Run /claw-whatsapp-add-account <account-id> to persist an account id for later reuse.
3. Run /claw-whatsapp-login <account-id> and scan the QR code.
4. Run /claw-whatsapp-pair-user <account-id> and let the user scan the pairing QR code.
5. The user sends the generated PAIR <code> message from WhatsApp.
6. Run /claw-whatsapp-bind-account <account-id>.
7. Open Coding Claw injects later WhatsApp task messages into the active session and replies briefly on WhatsApp when work starts and ends.

Included Capabilities

• hierarchical agent registry with per-role model defaults
• task delegation and execution policy enforcement
• peer-to-peer subagent messaging
• session-aware task tracking
• OpenCode tool surface for delegation, inbox reading, and session inspection
• LSP and AST toolkit exposure
• built-in MCP baseline for Context7, Tavily, and Playwright
• role-scoped MCP tool allocation with overrideable MCP profiles
• Python-backed desktop control runtime for Windows, macOS, and Linux
• optional semantic desktop providers: Windows via UI Automation, Linux via AT-SPI, macOS via System Events GUI scripting
• Baileys-based WhatsApp Web bridge with persisted auth state
• multi-account WhatsApp login state and runtime receive bindings
• QR-based per-account WhatsApp pairing for new users
• session injection for WhatsApp-originated prompts
• completion acknowledgement based on assistant message completion and session.idle fallback

Installation

For Humans

Paste this into your agent:

Install and configure Open Coding Claw by following the instructions here:
https://raw.githubusercontent.com/maoruiQa/open-claw-code/refs/heads/main/docs/guide/installation.md

Or read the full guide yourself:

• Installation Guide

For LLM Agents

Fetch the installation guide and follow it:

curl -fsSL https://raw.githubusercontent.com/maoruiQa/open-claw-code/refs/heads/main/docs/guide/installation.md

Prerequisites

• OpenCode
• Node.js with npm
• Git
• Python 3 for cross-platform desktop control
• a WhatsApp account if you want session-linked operator control

This repository ships as an OpenCode plugin package with:

• package name: open-coding-claw
• build output: dist/index.js
• config file: .opencode/open-coding-claw.jsonc

Configuration

Project config is loaded from:

• .opencode/open-coding-claw.jsonc
• .opencode/open-coding-claw.json

Example:

{
  "routing": {
    "maxFanOut": 4,
    "requireReviewForImplementation": true
  },
  "messaging": {
    "allowPeerToPeer": true
  },
  "whatsapp": {
    "enabled": true,
    "defaultAccount": "default",
    "allowedSenders": ["491234567890@c.us"],
    "authDir": ".opencode/whatsapp-session",
    "printQrInTerminal": true,
    "accounts": {
      "default": {
        "allowedSenders": ["491234567890@c.us"]
      },
      "ops": {
        "allowedSenders": ["491234567890@c.us"],
        "authDir": ".opencode/whatsapp-session/ops"
      }
    }
  },
  "agents": {
    "frontend-agent": {
      "model": "anthropic/claude-sonnet-4.6",
      "mcpProfile": "frontend-execution"
    },
    "explore-agent": {
      "model": "openai/gpt-5.4-mini"
    }
  },
  "mcp": {
    "enabled": true,
    "builtin": {
      "context7": true,
      "tavily": true,
      "playwright": true
    }
  }
}

Environment Notes

An example env file is included at .env.example.

Current example values cover:

• allowed WhatsApp senders
• WhatsApp auth/session directory
• computer-use screenshot directory
• default WhatsApp target
• optional TAVILY_API_KEY and CONTEXT7_API_KEY if you want header-based API-key auth instead of the default remote MCP auth flow

For full desktop control, install the Python packages used by the local driver:

pip install pyautogui pillow pywinctl pytesseract

Platform notes:

• macOS: grant Accessibility and Screen Recording permissions to the terminal or OpenCode host app
• Linux: run inside a graphical desktop session; xdg-open is used for opening paths/URLs
• OCR is optional and also needs the native Tesseract binary installed on the machine

Optional semantic desktop packages:

• Windows: pip install pywinauto
• Linux: install PyGObject/AT-SPI bindings for your distro so gi.repository.Atspi is available
• macOS: no extra Python package is required for the current System Events provider, but GUI scripting must be allowed

Development

npm run dev
npm run typecheck
npm run test
npm run build

Test Status

The current test suite covers:

• orchestration basics
• policy enforcement
• message bus behavior
• WhatsApp auth helpers
• WhatsApp inbound normalization
• WhatsApp receive bindings
• WhatsApp request tracking
• WhatsApp session injection

Repository Layout

src/
  agents/
  integrations/
  orchestrator/
  shared/
  tools/
tests/
docs/

Current Scope

Open Coding Claw is intentionally opinionated and still compact.

It already supports the core workflow:

• master-agent orchestration
• specialist delegation
• subagent-to-subagent messaging
• model specialization by role
• WhatsApp session control

Future work can extend this into a more productized experience, but the current repository already implements the central runtime model.

License

GPL-3.0-only