Openclaw_research

README

# openclaw_research

> Umbrella repo for the **Discord whitebox orchestration experiment**:
> a human, a Claude Code REPL, and an OpenClaw-backed codex agent all
> share one Discord channel and coordinate via `@mentions`. Two child
> repositories hold the actual code; this repo pins them as git
> submodules so the whole system is reproducible.

---

## What's inside

```
openclaw_research/
├── claudecode-discord-bridge/   → github.com/winehouse8/claudecode-discord-bridge
│                                  Local Node daemon. Owns claudecode-bot on
│                                  Discord, spawns a tmux-hosted Claude Code
│                                  REPL, converts mentions ↔ tmux ↔ hook events.
│
└── oh-my-claw/                  → github.com/winehouse8/oh-my-claw
                                   OpenClaw plugin. Registers as an agentic
                                   LLM critic on the `agent_end` + `message_sending`
                                   hooks so openclaw-bot can suppress and re-task
                                   a failing Claude Code run before the user sees it.
```

Both sub-repos are **git submodules**, so a fresh clone needs:

```bash
git clone --recurse-submodules https://github.com/winehouse8/openclaw_research.git
# or after a plain clone:
git submodule update --init --recursive
```

---

## The 3-way channel

```
#workspace
├── 👤 사람                          (your Discord account)
├── 🤖 claudecode-bot                (owned by bridge-daemon)
└── 🦞 openclaw-bot                  (owned by ai.openclaw.gateway)

@mention  →  routing  →  @reply  →  @mention  →  …

   사람 → @claudecode-bot "파일 고쳐줘"
      bridge-daemon: strip mention → tmux send-keys → Claude Code REPL
         Claude Code does work → OMC Stop hook → POST /hooks/agent
            bridge-daemon: reads transcript → posts Discord embed
               content: "@사람 @openclaw-bot · 🏁 완료" + result file
                  openclaw-gateway: sees @openclaw-bot mention → codex reads file
                     if OK: @사람 "재우님, 완료: ..."            (loop terminates)
                     if NG: @claudecode-bot /ralph "이것 빠짐"   (loop re-enters)
```

Everything is a visible Discord message. No hidden internal RPC.

---

## Component responsibilities

### `claudecode-discord-bridge`
- discord.js v14 client logged in as `claudecode-bot`
- tmux send-keys / capture-pane wrapper
- OMC hook HTTP receiver at `127.0.0.1:18850/hooks/agent`
- Per-request session tracking (caller id, git snapshot, injection timestamp)
- Transcript JSONL parser for the substantive final reply
- Multipart Discord message re-assembly for 2000-char splits
- Stuck-modal detection ("rate-limit-options", "How is Claude doing", ...)
- Bracket meta commands: `[help] [status] [peek] [reset] [new] [close] [cancel]`

### `oh-my-claw`
- OpenClaw plugin manifest (`openclaw.plugin.json`, `pluginApi >= 2026.4.12`)
- Hooks `agent_end` (capture-only) + `message_sending` (cancel + re-task)
- Agentic judge: spawns a `subagent.run` with read/write/bash tools to inspect
  the actual work product
- Per-channel rejection counter with `MAX_REJECTS = 3`
- Whitebox trail: posts rejection reasons as Discord embeds via the gateway
  delivery pipeline

**Relationship**: the two components coordinate through Discord messages, not
through direct IPC. The bridge never imports the plugin; the plugin never
touches tmux. Pure message passing.

---

## Why a single umbrella repo

1. **Reproducibility**: the system only works when these two components are
   at **compatible versions**. Pinning submodule SHAs records that
   compatibility.
2. **Discovery**: a contributor hitting this repo sees the 3-way architecture
   in one README instead of guessing which sub-project to start with.
3. **State isolation**: the parent has nothing except the submodule pointers
   and documentation. Each component keeps its own CI, tests, and release
   cadence independently.

---

## Setup (host side)

1. Install node 22+, tmux, Claude Code CLI, openclaw CLI.
2. Clone this repo with submodules (command above).
3. Follow `claudecode-discord-bridge/README.md` to configure the bridge daemon
   (env file + install-hooks).
4. Follow `oh-my-claw/README.md` to register the plugin with openclaw and
   enable it via `openclaw plugins enable oh-my-claw`.
5. Start bridge daemon; start `ai.openclaw.gateway` via launchd/systemd.
6. Test round-trip: in Discord, `@claudecode-bot [status]` → bridge responds.

---

## Status

Research-grade. Single contributor. Hosts a real daily workflow but the
API surface of both sub-repos changes without notice. See each submodule's
README for up-to-date capability and limitation lists.

---

## Related writing

Under `docs/` in the running monorepo:
- `discord-whitebox-communication-design.md` — the original design document
  for the 3-way Discord channel pattern
- `harness-engineering-on-openclaw.md` — research notes on Claude Code's
  hook system as it relates to OpenClaw integration