openclaw-cc-direct

Fork Notice: This project is a fork of openclaw-cc-bridge by @cadl. Original project renamed and enhanced with session key unification, multi-instance safety, and other improvements.

OpenClaw plugin for controlling Claude Code via chat platforms.

openclaw-cc-direct bridges OpenClaw chat commands with Claude Code CLI, enabling users to send prompts, manage sessions, plan and execute code changes, and track tool usage directly from any OpenClaw-connected chat platform.

Features

• Chat-driven Claude Code — Send prompts and receive results via /cc commands
• Plan / Execute workflow — Create read-only plans with /cc_plan, review, then execute with /cc_execute
• Agent tools — LLM-callable tools (cc_send, cc_plan, cc_execute, etc.) for AI agent integration
• Pending question handling — Claude Code's AskUserQuestion prompts are surfaced to chat; reply via /cc
• Multi-workspace sessions — Each sender can manage multiple workspace sessions independently
• Session persistence — Multi-turn conversations survive plugin restarts
• File-based hook tracking — Claude Code hook events (tool use, subagent lifecycle) captured via file-based inbox
• Event persistence — Full audit trail of stream events and hook events stored to disk
• Timeout retry — Automatic retry with --resume on Claude Code timeout (configurable max retries)
• Debug UI — Built-in web interface with WebSocket live streaming for development

Commands

Flags:

• -m <model> / --model <model> — Override model for this invocation (sonnet, opus, haiku, sonnet[1m], opusplan)
• -w <path> / --workspace <path> — Target a specific workspace
• -n / --new — Force a new Claude Code session instead of resuming

Agent Tools

The plugin registers LLM-callable tools via registerTool, allowing AI agents to invoke Claude Code programmatically:

All tools accept optional workspace and model parameters.

Session Management

Slash commands and agent tools use asymmetric defaults to align Claude Code sessions with OpenClaw conversation boundaries:

This asymmetry works because:

• Slash commands are typed by the user within a continuous conversation — resuming is the natural default, with --new for explicit resets.
• Agent tools are called by the LLM. After OpenClaw's /new command, the LLM loses all prior context and won't set continue_session: true, so a fresh Claude Code session starts automatically.

Special cases:

• If Claude Code asked a question (pendingQuestion), the next call always resumes regardless of flags.
• cc_execute always resumes the plan session.

Skills

The plugin ships an OpenClaw skill (cc-direct) that lets the AI agent automatically recognize coding requests and invoke Claude Code without the user needing to type explicit slash commands. The skill is gated on claude CLI being available on PATH.

When the skill is loaded, users can simply describe what they want in natural language (e.g., "fix the auth bug in login.ts") and the AI agent will route the request to Claude Code via the appropriate tool.

Quick Start

Prerequisites

• Node.js 18+
• Claude Code CLI installed and authenticated
• An OpenClaw instance

Install

openclaw plugin add openclaw-cc-direct

Or install manually via npm:

npm install openclaw-cc-direct

Configuration

Register the plugin in your OpenClaw setup. The plugin reads from openclaw.plugin.json and exports its entry point from dist/plugin/index.js.

Plugin config (via OpenClaw API):

Example config:

{
  "model": "sonnet",
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-api-relay.example.com",
    "ANTHROPIC_API_KEY": "sk-..."
  },
  "allowedTools": ["Read", "Edit", "Write", "Bash", "Glob", "Grep", "Task"]
}

Note: If ANTHROPIC_BASE_URL points to a LAN address and the gateway runs as a macOS launchd agent, local network connections may be blocked by macOS Local Network Privacy. See troubleshoot.md for details.

Environment variables:

Recommended Configuration

For the best experience, especially if you communicate in non-English languages, add the configuration snippets from SOUL_CONFIGURATION.md to your OpenClaw workspace SOUL.md file.

This ensures:

• Your original language is preserved when sending prompts to Claude Code
• You receive complete, unmodified output from Claude Code sessions

Architecture

Chat Platform
    │
    ▼
 OpenClaw ──► openclaw-cc-direct plugin
                 │
                 ├── RunManager ──► orchestrates each execution
                 │     ├── ClaudeBridge ──► claude CLI (child process, NDJSON streaming)
                 │     ├── HookInbox ──► file-based hook capture (fs.watch + polling)
                 │     └── EventStore ──► store/ (stream + hook events per session)
                 │
                 └── SessionManager ──► sessions.json (sender → multi-workspace sessions)

Modules

Data Layout

~/.openclaw/openclaw-cc-direct/
├── sessions.json                 # sender → multi-workspace session mappings
├── hook-inbox/
│   └── events.jsonl              # shared hook event inbox (watched by HookInbox)
└── store/
    ├── index.json                # session index
    └── sessions/
        └── <sessionId>/
            ├── meta.json         # session metadata (cost, duration, model, firstPrompt)
            ├── stream.jsonl      # raw NDJSON stream events
            └── hooks.jsonl       # hook callback events

Development

# Watch mode
npm run dev

# Launch debug server (compile + start)
npm run debug

The debug server starts at http://localhost:3456 and provides a web UI for sending prompts, viewing live events, inspecting session history, and testing plan/execute workflows.

License

MIT