Delegates tasks to the local Claude Code CLI. Activate immediately when the user asks for Claude, requests a stronger model, or mentions an existing project...
---
name: claw2claude
description: "Delegates tasks to the local Claude Code CLI. Activate immediately when the user asks for Claude, requests a stronger model, or mentions an existing project path. Ask the user first whether to create a Claude project when: the task involves building something from scratch, spans multiple parts, requires multiple rounds of iteration, or the user is expressing a direction rather than a concrete single question. Applies to code AND non-code work (business plans, product specs, docs, etc.). Do not start answering directly — ask first."
license: MIT
metadata:
openclaw:
os: darwin
emoji: "🦞→🤖"
requires:
bins:
- claude
- python3
reads:
- ~/.openclaw/openclaw.json # gateway port + auth token for result delivery
- ~/.openclaw/credentials/ # JWT token health check (read-only, warnings only)
- ~/.openclaw/agents/main/sessions/sessions.json # auto-detect user's active channel
writes:
- <project_path>/.openclaw-claude-session.json # session state (git-ignored)
- <project_path>/.claude-last-run.log # full Claude output log
- <project_path>/.claude-notify.json # IPC file between Claude and notifier
- <skill_dir>/logs/YYYY-MM.log # monthly invocation log
background_processes:
- notifier.py # polls for Claude completion, delivers chunked results via gateway; exits automatically on delivery
- heartbeat.py # used in background mode only; monitors Claude PID, notifies on completion
gateway_tools_used:
- message # sends result chunks to the user's channel
config_changes_required:
- gateway.tools.allow: ["message"] # allow notifier to send messages from outside an AI turn
- tools.sessions.visibility: "all" # allow notifier to message across sessions
permissions:
claude_flags: "--dangerously-skip-permissions" # Claude runs fully automated; no interactive prompts
rationale: >-
Required for non-interactive use. Claude Code is triggered by a chat
message (not a terminal session) and cannot present permission prompts
to the user. All file/tool access is bounded to the specified project
directory; no system-level writes occur.
---
# claw2claude — OpenClaw Orchestrates Claude Code
Delegates the user's task to the local `claude` CLI.
**You (OpenClaw AI) are the orchestrator. Claude Code is the executor.**
---
## Security & Transparency
This skill has broader-than-average system access because it bridges two runtimes (OpenClaw and Claude Code). Everything it does is documented here and in the metadata above.
### What this skill accesses
| Resource | Why | Access type |
|----------|-----|-------------|
| `~/.openclaw/openclaw.json` | Gateway port + auth token, so `notifier.py` can POST results back to the user's channel | Read-only |
| `~/.openclaw/credentials/` | JWT expiry check before Claude starts — warns if token is stale; never modifies | Read-only |
| `~/.openclaw/agents/main/sessions/sessions.json` | Find the user's most recently active channel so results go to the right place | Read-only |
| `<project_path>/` | Claude Code working directory; all file changes are intentional outputs of the delegated task | Read + write |
| `<skill_dir>/logs/` | Monthly invocation log (timestamp, mode, project, exit status, no prompt content beyond first 200 chars) | Write |
### Background processes
Two scripts run detached from the main AI turn:
- **`notifier.py`** — starts when Claude starts; polls every 2 s for Claude's completion file; sends chunked results to the user's channel via the OpenClaw gateway `message` tool; **exits immediately after delivery** (or after 35 min if Claude never finishes).
- **`heartbeat.py`** — used in `background` mode only; monitors the background Claude PID; sends a notification when Claude exits. Not used in `discuss`, `execute`, or `continue` modes.
Neither process modifies OpenClaw config, reads credentials a second time, or persists beyond the task lifecycle.
### `--dangerously-skip-permissions` usage
All Claude sessions are launched with this flag. It is necessary because Claude Code is invoked non-interactively (triggered by a chat message, not a terminal), so it cannot display permission prompts. The flag's scope is limited to the project directory — Claude is not given broader system access than a normal Claude Code session would have.
If you prefer interactive permission prompts, run Claude Code directly in a terminal rather than through this skill.
### Required `openclaw.json` changes
Two config changes must be applied before the skill works. These are opt-in — the skill cannot make these changes itself:
```json
{
"gateway": {
"tools": { "allow": ["message"] }
},
"tools": {
"sessions": { "visibility": "all" }
}
}
```
- **`gateway.tools.allow: ["message"]`** — lets `notifier.py` call the gateway `message` tool from outside an AI turn to deliver results
- **`tools.sessions.visibility: "all"`** — lets the notifier target the user's channel session (which differs from the system session running Claude)
See README.md for the full setup guide.
---
## Activation
### A. Activate immediately (any one condition is enough)
| Condition | Examples |
|-----------|---------|
| User explicitly asks for Claude | "use Claude for this", "let Claude handle it", "hand it to Claude" |
| User requests a stronger / smarter model | "use a better model", "switch to a more capable AI" |
| Task involves an existing Claude Code project | User mentions a path that contains `.openclaw-claude-session.json` |
| User explicitly mentions claude CLI / Claude Code | "run it with claude", "open a Claude Code session" |
### B. Ask first (when you judge the task has these traits)
Before starting, ask the user whether to create a Claude project if any of the following apply:
| Trait | How to judge |
|-------|-------------|
| **It's an idea or direction** | User says "I want to build/design/plan/write a…" — no concrete single question yet |
| **Multiple parts involved** | Feature modules, document chapters, plan phases — not answerable in one reply |
| **Multiple iterations expected** | Discuss → revise → confirm loop, or clearly not a one-shot Q&A |
| **A clear project concept exists** | App, system, business plan, product spec, docs, course outline, campaign plan, etc. |
| **User already has related material** | Mentions an existing directory, codebase, docs, or prior discussion |
**Fixed phrasing to use when asking:**
> This looks like a task that will need multiple rounds of discussion or iteration.
> Would you like to set up a Claude Code project for this? Benefits:
> - Full conversation history and context that persists across sessions
> - Pick up where you left off at any time
> - All files, plans, and code kept in one working directory
>
> **[Yes, create project]** / **[No, handle it directly]**
- User says **yes**: ask for (or suggest) a project path, then launch in `discuss` or `execute` mode
- User says **no**: handle it yourself; do not invoke this skill
**If none of the above conditions apply, handle the request yourself. Do not invoke this skill.**
---
## Four Modes
| Mode | When to use | Claude permissions |
|------|-------------|-------------------|
| `discuss` | Requirements are unclear; user wants to explore options or plan architecture | `--dangerously-skip-permissions` (all operations allowed) |
| `execute` | Task is clear; user wants code written or changed | `--dangerously-skip-permissions` (fully automatic) |
| `continue` | Resuming the previous session in the same mode | Inherits the previous mode's permissions |
| `background` | User wants Claude to run without waiting for the result | Same as execute (`--dangerously-skip-permissions`) — always runs as execute, cannot use discuss or continue |
**Claude has a 30-minute timeout.** If it expires, the task is aborted — split it into smaller subtasks and retry.
---
## Step 1: Determine the mode
| What the user says | Mode |
|--------------------|------|
| "Help me think through how to design…" / "What are the options?" / "Analyse this…" | `discuss` |
| "Write…" / "Implement…" / "Create…" / "Refactor…" | `execute` |
| "Continue" / "Keep going" / "Do what we discussed" | `continue` |
| After a discussion: "OK, let's build it" / "Go with that plan" | `execute` ← important! |
| "Run it in the background" / "Don't wait, just let it run" | `background` |
> ⚠️ **Use `execute`, not `continue`, when switching from discussion to implementation.**
> `execute` always resumes the last session (`--resume`) if one exists, whether the previous mode was `discuss` or `execute`.
> This keeps all messages to the same project in a single continuous session.
> `continue` also resumes the same session but is reserved for explicit "pick up where we left off" requests.
>
> If the user says "continue" but also adds a new direction, use `execute` mode with the full structured prompt — not `continue`.
---
## Step 2: Confirm the project path (critical — prevents session cross-contamination)
The registry is printed to stderr automatically each time `launch.sh` runs — you do not need a separate call unless you need to inspect it *before* deciding which project to use. If unsure, run:
```bash
python3 "$SKILL_DIR/scripts/projects.py" list
```
| Situation | Action |
|-----------|--------|
| User specified a path explicitly | Use it directly |
| Registry is empty — brand new project | Generate an English directory name from the task; tell the user: `"I'll create the project at ~/Projects/<name> — let me know if you'd like a different location"` |
| Registry has exactly one project | Use it by default; tell the user: `"Continuing with [project name]"` |
| Registry has multiple projects + user says "continue" but it's ambiguous | **List them and ask the user to choose. Never guess.** |
| Registry has multiple projects + task implies a specific one | Infer and confirm: `"Did you mean [project name]?"` |
---
## Step 3: Build the prompt for Claude
Expand the user's raw description into a structured instruction that Claude can execute efficiently.
**discuss mode** — instruct Claude to act as an architecture advisor, suggestions only, no code:
```
You are an experienced software architect. The user wants to discuss the following:
<user's original request>
Ask clarifying questions, suggest architecture patterns and tech stack options, identify risks.
Do NOT write actual implementation code unless the user explicitly asks for a short example.
```
**execute mode** — instruct Claude to complete the task directly:
```
You are a professional software engineer. Complete the following task:
Goal: <clear description of the end result>
Tech stack: <language/framework — infer if not specified>
Requirements:
- Clean, commented code following best practices
- Proper error handling and edge case coverage
- <any specific requirements the user emphasised>
<list concrete steps if applicable; omit otherwise>
```
**continue mode** — pass the user's new instruction directly; Claude already has the full prior context:
```
<user's new instruction verbatim>
```
---
## Step 4: Launch and notify (required)
**Before invoking Claude Code, tell the user it's starting** (say it in your reply — no extra tool needed):
`"🚀 Launching Claude Code for [project name] — [discuss/execute] mode. This will take a few minutes…"`
Then run with the `exec` tool:
```bash
"$SKILL_DIR/scripts/launch.sh" "<project_path>" "<mode>" "<prompt>"
```
- `project_path`: absolute path — the script creates the directory and runs `git init` automatically
- `mode`: `discuss` / `execute` / `continue` / `background`
- `prompt`: the structured instruction built in Step 3. If the prompt contains double quotes, escape them as `\"` or wrap in single quotes.
> ⚠️ **Never pass a 4th argument.** The session key is always auto-detected by `launch.sh`. Passing it manually risks arg-parse corruption: when the prompt contains newlines or special characters, the shell may miscount positional arguments and assign prompt content to `$4`, sending results to the wrong channel.
**background mode**: the script returns immediately; Claude runs in the background. Tell the user:
`"🚀 Claude Code is running in the background. You'll be notified automatically when it's done."`
---
## Step 5: Deliver the result
The exec result already contains a **structured summary written by Claude** (extracted from the `---CHAT_SUMMARY---` block). The full output is in the log file.
The exec call may have taken several minutes and the channel connection may be stale. **Always use the `message` tool explicitly** to guarantee delivery — do not rely on turn-response auto-routing.
### Chunked delivery (required — do not send in one message)
Split the summary into chunks and send each as a **separate `message` call**. Rules:
1. **First message**: one-line confirmation only → `"✅ Claude Code finished · [project name]"`
2. **Body chunks**: split the summary by section headings (`##`, `###`) or at natural paragraph breaks — whichever comes first. Each chunk must be **≤ 500 characters**. If a single paragraph exceeds 500 characters, break it at the nearest sentence boundary.
3. **Last message**: footer line only →
- discuss mode: omit the footer — do not add any fixed closing line; let the summary speak for itself and ask a natural follow-up question if appropriate
- execute mode: `"Please verify the result in your project directory."`
- on timeout: `"⏰ Task timed out (>30 min) — please split it into smaller subtasks and retry."`
Do not rewrite or expand the summary — Claude already wrote it concisely. Send each chunk verbatim.
**Example** (summary has 3 sections):
```
message("✅ Claude Code finished · myapp")
message("## What was done\nAdded JWT middleware to …")
message("## Files changed\n- src/auth.ts\n- src/routes …")
message("## Next steps\nRun `npm test` to verify …")
message("Please verify the result in your project directory.")
```
---
## Examples
```
User: I want to build a video transcription tool but I'm not sure which tech stack to use
→ discuss mode → confirm directory ~/Projects/video-transcriber
→ Claude analyses options
User: OK, let's go with Whisper + FastAPI — start building
→ execute mode (discuss→execute, carries over context via --resume)
→ Claude implements directly based on the discussion, no need to re-explain
User: Add JWT authentication to ~/Projects/myapp
→ execute mode, path is explicit
User: Continue
→ registry has two projects → list them and ask the user to choose
```
don't have the plugin yet? install it then click "run inline in claude" again.