@betrue/openclaw-claude-code-plugin 1.0.0

package/README.md

@@ -0,0 +1,599 @@
+# Claude Code Plugin
+
+**An OpenClaw plugin that orchestrates Claude Code sessions as managed background processes.**
+
+Claude Code Plugin lets you launch, monitor, and interact with multiple Claude Code SDK sessions directly from any OpenClaw channel (Telegram, Discord, etc.). It turns OpenClaw into a control plane for autonomous coding agents — launch tasks, stream output in real time, send follow-up messages, resume previous conversations, and catch up on missed output — all without leaving your chat interface.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Architecture](#architecture)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [Chat Commands](#chat-commands)
+  - [Agent Tools](#agent-tools)
+  - [Gateway RPC Methods](#gateway-rpc-methods)
+- [API Reference](#api-reference)
+  - [Tools](#tools)
+  - [Commands](#commands)
+  - [RPC Methods](#rpc-methods)
+- [Notification System](#notification-system)
+- [Skill Example: Coding Agent Workflow](#skill-example-coding-agent-workflow)
+- [Development](#development)
+
+---
+
+## Features
+
+- **Multi-session management** — Run up to N concurrent Claude Code sessions (configurable), each tracked with a unique ID and human-readable name.
+- **Foreground / background model** — Sessions run in the background by default. Bring any session to the foreground to stream output in real time, then detach without interrupting work.
+- **Foreground catchup** — When you bring a session to the foreground with `claude_fg`, any output produced while it was in the background is displayed under a "📋 Catchup (N missed outputs):" header before live streaming begins, so you never miss anything.
+- **Multi-turn conversations** — Launch sessions in multi-turn mode to send follow-up messages, refine instructions, or have iterative dialogues with a running agent.
+- **Session resume & fork** — Resume any completed session from where it left off, or fork it into a new branch of conversation.
+- **Real-time notifications** — Completion alerts, session-limit warnings, long-running session reminders, and live tool-use indicators delivered to your chat.
+- **Channel propagation** — `claude_launch`, `claude_fg`, and `claude_bg` accept an optional `channel` parameter (e.g. `"telegram:123456789"`) so notifications are routed to the correct user channel instead of falling back to `"unknown"`.
+- **Waiting-for-input wake events** — When any session (single or multi-turn) becomes idle and waiting for input, an `openclaw system event` is fired to wake the orchestrator. Uses end-of-turn detection for multi-turn results plus a 15-second safety-net timer. A `waitingForInputFired` guard prevents duplicate events.
+- **Background visibility** — Even when sessions run in the background, users see `🔔 Claude asks:` when the agent needs input and `↩️ Responded:` when a follow-up is sent — the full conversation stays visible in-channel.
+- **Session metrics** — Per-session tracking, session counts by status, average duration, and notable-session reporting (internally tracked).
+- **Triple interface** — Every operation is available as a chat command (for humans), an agent tool (for the OpenClaw AI), and a gateway RPC method (for external systems).
+- **Automatic cleanup** — Completed sessions are garbage-collected after 1 hour; persisted session IDs survive for resume support (up to a configurable cap).
+- **Agent event triggers** — When a session completes or becomes idle waiting for input, an OpenClaw system event is fired so the AI agent can immediately process the result or provide follow-up instructions.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    index.ts                         │
+│              (Plugin entry point)                   │
+│  Registers tools, commands, RPC methods, service    │
+└──────────────┬──────────────────────────────────────┘
+               │
+      ┌────────┼─────────────────┐
+      │        │                 │
+      ▼        ▼                 ▼
+  Tools    Commands          Gateway RPC
+  (8)      (8)               (5 methods)
+      │        │                 │
+      └────────┼─────────────────┘
+               │
+               ▼
+        ┌─────────────┐     ┌────────────────────┐
+        │   shared.ts  │────▶│  SessionManager    │
+        │  (globals,   │     │  (spawn, resolve,  │
+        │   helpers)   │     │   kill, cleanup,   │
+        │              │     │   metrics, persist)│
+        └─────────────┘     └────────┬───────────┘
+                                     │
+                            ┌────────┴───────────┐
+                            │     Session        │
+                            │  (Claude SDK       │
+                            │   query() wrapper, │
+                            │   message stream,  │
+                            │   abort, output)   │
+                            └────────────────────┘
+                                     │
+                            ┌────────┴───────────┐
+                            │ NotificationRouter │
+                            │  (foreground       │
+                            │   streaming,       │
+                            │   catchup display, │
+                            │   completion,      │
+                            │   session-limit,   │
+                            │   long-run remind) │
+                            └────────────────────┘
+```
+
+### Key Components
+
+| Component | File | Responsibility |
+|---|---|---|
+| **Session** | `src/session.ts` | Wraps the Claude Agent SDK `query()` call. Manages the async message stream, output buffering (last 200 blocks), abort control, multi-turn `MessageStream`, idle timeouts, waiting-for-input detection (end-of-turn + 15s safety-net timer with `waitingForInputFired` guard), and event callbacks (`onOutput`, `onToolUse`, `onComplete`, `onSessionLimitReached`). |
+| **SessionManager** | `src/session-manager.ts` | Manages the pool of active sessions. Enforces `maxSessions`, generates unique names, wires notification callbacks, persists Claude session IDs for resume, records metrics, triggers agent events on completion and waiting-for-input, and runs periodic garbage collection. |
+| **NotificationRouter** | `src/notifications.ts` | Routes events to the right chat channels. Debounces foreground text streaming (500ms), shows compact tool-use indicators, sends completion/failure/session-limit notifications, foreground catchup display, and periodically checks for sessions running longer than 10 minutes. |
+| **Gateway** | `src/gateway.ts` | Exposes 5 JSON-RPC methods for external/programmatic access. |
+| **Shared** | `src/shared.ts` | Global singletons (`sessionManager`, `notificationRouter`, `pluginConfig`), helper functions (name generation, duration formatting, session listing, stats formatting), and channel resolution logic. |
+| **Types** | `src/types.ts` | TypeScript interfaces: `SessionConfig`, `ClaudeSession`, `PluginConfig`, `SessionStatus`, `PermissionMode`. |
+
+---
+
+## Installation
+
+### From npm
+
+```bash
+openclaw plugins install @betrue/openclaw-claude-code-plugin
+```
+
+### From source (git clone)
+
+```bash
+git clone git@github.com:alizarion/openclaw-claude-code-plugin.git
+openclaw plugins install ./openclaw-claude-code-plugin
+```
+
+### For development (symlink)
+
+```bash
+git clone git@github.com:alizarion/openclaw-claude-code-plugin.git
+openclaw plugins install --link ./openclaw-claude-code-plugin
+```
+
+### After installation
+
+Restart the gateway to load the plugin:
+
+```bash
+openclaw gateway restart
+```
+
+Ensure `openclaw` CLI is available in your PATH — the plugin shells out to `openclaw message send` for notifications and `openclaw system event` for agent triggers.
+
+---
+
+## Configuration
+
+Configuration is defined in `openclaw.plugin.json` under `configSchema` and passed to the plugin at service start via `api.getConfig()`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `maxSessions` | `number` | `5` | Maximum number of concurrently active (starting/running) sessions. |
+| `defaultBudgetUsd` | `number` | `5` | Default max budget in USD for new sessions when not explicitly specified. |
+| `defaultModel` | `string` | — | Default model for new sessions (e.g. `"sonnet"`, `"opus"`). |
+| `defaultWorkdir` | `string` | — | Default working directory for new sessions. Falls back to `process.cwd()`. |
+| `idleTimeoutMinutes` | `number` | `30` | Idle timeout for multi-turn sessions. If no follow-up message is sent within this window, the session is auto-killed. |
+| `maxPersistedSessions` | `number` | `50` | Maximum number of completed sessions to keep in memory for resume support. Oldest sessions are evicted when the cap is exceeded. |
+| `fallbackChannel` | `string` | — | Fallback notification channel (e.g. `"telegram:123456789"`). Used when the origin channel cannot be determined. |
+| `permissionMode` | `string` | `"bypassPermissions"` | Default permission mode for Claude Code sessions. One of: `"default"`, `"plan"`, `"acceptEdits"`, `"bypassPermissions"`. |
+
+### Example configuration
+
+```json
+{
+  "maxSessions": 3,
+  "defaultBudgetUsd": 10,
+  "defaultModel": "sonnet",
+  "defaultWorkdir": "/home/user/projects",
+  "idleTimeoutMinutes": 60,
+  "maxPersistedSessions": 100,
+  "fallbackChannel": "telegram:123456789",
+  "permissionMode": "bypassPermissions"
+}
+```
+
+---
+
+## Usage
+
+### Chat Commands
+
+Commands are invoked by humans in chat (Telegram, Discord, etc.) with a `/` prefix.
+
+```
+/claude Fix the authentication bug in src/auth.ts
+/claude --name fix-auth Fix the authentication bug in src/auth.ts
+/claude_sessions
+/claude_fg fix-auth
+/claude_bg
+/claude_bg fix-auth
+/claude_kill fix-auth
+/claude_respond fix-auth Also add unit tests for the fix
+/claude_respond --interrupt fix-auth Stop, use a different approach
+/claude_resume --list
+/claude_resume fix-auth Add error handling to the login flow
+/claude_resume --fork fix-auth Try a completely different approach
+/claude_stats
+```
+
+### Agent Tools
+
+Tools are invoked by the OpenClaw AI agent programmatically. They follow the MCP tool calling convention.
+
+```
+claude_launch(prompt: "Fix auth bug", workdir: "/app", name: "fix-auth")
+claude_launch(prompt: "Refactor DB layer", multi_turn: true, channel: "telegram:123456789")
+claude_launch(prompt: "Continue", resume_session_id: "abc123", fork_session: true)
+claude_sessions(status: "running")
+claude_output(session: "fix-auth", full: true)
+claude_fg(session: "fix-auth", channel: "telegram:123456789")
+claude_bg(session: "fix-auth", channel: "telegram:123456789")
+claude_kill(session: "fix-auth")
+claude_respond(session: "fix-auth", message: "Also add tests", interrupt: false)
+claude_stats()
+```
+
+### Gateway RPC Methods
+
+RPC methods are called by external clients (dashboards, APIs, other plugins) via the OpenClaw gateway.
+
+```json
+// Launch a session
+{ "method": "claude-code.launch", "params": { "prompt": "Fix auth", "workdir": "/app" } }
+
+// List sessions
+{ "method": "claude-code.sessions", "params": { "status": "running" } }
+
+// Get output
+{ "method": "claude-code.output", "params": { "session": "fix-auth", "full": true } }
+
+// Kill a session
+{ "method": "claude-code.kill", "params": { "session": "fix-auth" } }
+
+// Get stats
+{ "method": "claude-code.stats" }
+```
+
+---
+
+## API Reference
+
+### Tools
+
+#### `claude_launch`
+
+Launch a new Claude Code session.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `prompt` | `string` | Yes | The task prompt to execute. |
+| `name` | `string` | No | Human-readable name (kebab-case). Auto-generated from prompt if omitted. |
+| `workdir` | `string` | No | Working directory. Defaults to config `defaultWorkdir` or `cwd`. |
+| `model` | `string` | No | Model name (e.g. `"sonnet"`, `"opus"`). |
+| `max_budget_usd` | `number` | No | Maximum budget in USD. Default: `5`. |
+| `system_prompt` | `string` | No | Additional system prompt appended to the session. |
+| `allowed_tools` | `string[]` | No | Explicit list of allowed tools. |
+| `resume_session_id` | `string` | No | Claude session ID (or name/internal ID) to resume from. |
+| `fork_session` | `boolean` | No | Fork instead of continuing when resuming. |
+| `multi_turn` | `boolean` | No | Enable multi-turn mode for follow-up messages via `claude_respond`. |
+| `permission_mode` | `string` | No | One of `"default"`, `"plan"`, `"acceptEdits"`, `"bypassPermissions"`. |
+| `channel` | `string` | No | Origin channel for notifications (e.g. `"telegram:123456789"`). Prevents `"unknown"` routing. |
+
+#### `claude_sessions`
+
+List all sessions with status and progress.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `status` | `string` | No | Filter: `"all"` (default), `"running"`, `"completed"`, `"failed"`. |
+
+#### `claude_output`
+
+Show output from a session.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `session` | `string` | Yes | Session name or ID. |
+| `lines` | `number` | No | Number of recent lines to show (default 50). |
+| `full` | `boolean` | No | Show all available output (up to 200 buffered blocks). |
+
+#### `claude_fg`
+
+Bring a session to foreground — displays any missed background output under a "📋 Catchup (N missed outputs):" header, then starts streaming new output to the current channel in real time.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `session` | `string` | Yes | Session name or ID. |
+| `lines` | `number` | No | Number of recent buffered lines to show (default 30). |
+| `channel` | `string` | No | Target channel for streaming (e.g. `"telegram:123456789"`). Prevents `"unknown"` routing. |
+
+#### `claude_bg`
+
+Send a session back to background (stop streaming).
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `session` | `string` | No | Session name or ID. If omitted, detaches all foreground sessions for the current channel. |
+| `channel` | `string` | No | Channel to detach from (e.g. `"telegram:123456789"`). Prevents `"unknown"` routing. |
+
+#### `claude_kill`
+
+Terminate a running session.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `session` | `string` | Yes | Session name or ID. |
+
+#### `claude_respond`
+
+Send a follow-up message to a running session.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `session` | `string` | Yes | Session name or ID. |
+| `message` | `string` | Yes | The message to send. |
+| `interrupt` | `boolean` | No | Interrupt the current turn before sending. Useful to redirect mid-response. |
+
+#### `claude_stats`
+
+Show usage metrics. Takes no parameters.
+
+Returns: session counts by status, average duration, and notable session (sorted by cost internally — cost values are not shown in user-facing output).
+
+---
+
+### Commands
+
+All commands require authentication (`requireAuth: true`).
+
+| Command | Arguments | Description |
+|---|---|---|
+| `/claude [--name <name>] <prompt>` | Required: prompt | Launch a new session. |
+| `/claude_sessions` | None | List all sessions. |
+| `/claude_kill <name-or-id>` | Required: session ref | Terminate a session. |
+| `/claude_fg <name-or-id>` | Required: session ref | Bring a session to foreground. |
+| `/claude_bg [name-or-id]` | Optional: session ref | Detach foreground session(s). |
+| `/claude_resume <ref> [prompt]` | Required: session ref | Resume a completed session. |
+| `/claude_resume --list` | Flag | List all resumable sessions. |
+| `/claude_resume --fork <ref> [prompt]` | Required: session ref | Fork a completed session. |
+| `/claude_respond <ref> <message>` | Required: session ref + message | Send a follow-up message. |
+| `/claude_respond --interrupt <ref> <msg>` | Flag + session ref + message | Interrupt then send. |
+| `/claude_stats` | None | Show usage metrics. |
+
+---
+
+### RPC Methods
+
+All methods return `respond(true, data)` on success or `respond(false, { error })` on failure.
+
+#### `claude-code.sessions`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `status` | `string` | Filter: `"all"`, `"running"`, `"completed"`, `"failed"`. |
+
+**Response:** `{ sessions: [...], count: number }`
+
+Each session object includes: `id`, `name`, `status`, `prompt`, `workdir`, `model`, `startedAt`, `completedAt`, `durationMs`, `claudeSessionId`, `foreground`, `multiTurn`, `display`.
+
+#### `claude-code.launch`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `prompt` | `string` | **(required)** Task prompt. |
+| `name` | `string` | Session name. |
+| `workdir` | `string` | Working directory. |
+| `model` | `string` | Model name. |
+| `maxBudgetUsd` / `max_budget_usd` | `number` | Budget cap. |
+| `systemPrompt` / `system_prompt` | `string` | System prompt. |
+| `allowedTools` / `allowed_tools` | `string[]` | Allowed tools. |
+| `resumeSessionId` / `resume_session_id` | `string` | Session ID to resume. |
+| `forkSession` / `fork_session` | `boolean` | Fork on resume. |
+| `multiTurn` / `multi_turn` | `boolean` | Multi-turn mode. |
+| `originChannel` | `string` | Origin channel for notifications. |
+
+**Response:** `{ id, name, status, workdir, model }`
+
+#### `claude-code.kill`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `session` / `id` | `string` | **(required)** Session name or ID. |
+
+**Response:** `{ id, name, status, message }`
+
+#### `claude-code.output`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `session` / `id` | `string` | **(required)** Session name or ID. |
+| `lines` | `number` | Number of lines (default 50). |
+| `full` | `boolean` | Return all buffered output. |
+
+**Response:** `{ id, name, status, durationMs, duration, lines, lineCount, result }`
+
+#### `claude-code.stats`
+
+No parameters.
+
+**Response:**
+```json
+{
+  "sessionsByStatus": { "completed": 10, "failed": 2, "killed": 1, "running": 1 },
+  "totalLaunched": 14,
+  "averageDurationMs": 45000,
+  "notableSession": { "id": "abc123", "name": "refactor-db", "prompt": "..." },
+  "display": "📊 Claude Code Plugin Stats\n..."
+}
+```
+
+---
+
+## Notification System
+
+The `NotificationRouter` implements a notification matrix based on session state and channel mode:
+
+| Event | Background session | Foreground session |
+|---|---|---|
+| Session started | Silent | Silent (streaming begins) |
+| Assistant text output | Silent | Streamed to chat (500ms debounce) |
+| Tool call | Silent | Compact indicator (e.g. `🔧 Bash — git status`) |
+| Tool result | Silent | Silent |
+| Session completed (success) | Notify origin channel | Notify all channels |
+| Session completed (error) | Notify origin channel | Notify all channels |
+| Session limit reached | Notify origin channel | Notify all channels |
+| Session > 10 minutes | One-time reminder | Silent (user sees output) |
+| Waiting for input | `🔔 [name] Claude asks:` + preview to origin channel + fire `openclaw system event` | `💬 Session waiting for input` + fire `openclaw system event` |
+| Agent responds (`claude_respond`) | `↩️ [name] Responded:` echoed to origin channel | `↩️ [name] Responded:` echoed to origin channel |
+
+### Notification delivery
+
+Notifications are sent via the `openclaw message send` CLI command. The channel ID format is `"channel:target"` (e.g. `"telegram:123456789"`, `"discord:987654321"`). Bare numeric IDs are assumed to be Telegram chat IDs.
+
+### Background visibility
+
+When a session is running in the background, users can follow the conversation without foregrounding:
+
+- **🔔 Claude asks** — When a session becomes idle and waiting for input (e.g. Claude asked a question or needs a decision), the origin channel receives a `🔔 [name] Claude asks:` message with a preview of the last output, so the user sees what Claude needs.
+- **↩️ Responded** — When the agent (or user via `claude_respond`) sends a follow-up message, a `↩️ [name] Responded:` message is echoed to the origin channel with the response content, so the full conversation is visible in-channel.
+
+This makes the plugin a transparent transport layer — the user sees both sides of the conversation in their chat, even when sessions run in the background.
+
+### Agent event triggers
+
+When a session completes, an `openclaw system event` is fired with a summary of the session result, prompting the OpenClaw AI agent to process the output and relay it to the user.
+
+When any session (single or multi-turn) becomes idle and waiting for input, an `openclaw system event` is also fired to wake the orchestrator. Idle detection uses end-of-turn detection (for multi-turn results) combined with a 15-second safety-net timer. A `waitingForInputFired` flag prevents duplicate wake events from being fired for the same idle period.
+
+---
+
+## Skill Example: Coding Agent Workflow
+
+Claude Code Plugin is a **transparent transport layer** — it spawns sessions, streams output, and delivers notifications, but it has no opinion about *how* to orchestrate coding agents. Business logic lives in **OpenClaw skills**.
+
+Here's an example skill that defines a coding agent workflow: it auto-responds to certain Claude questions and forwards others to the user.
+
+### `coding-agent.skill.yaml`
+
+```yaml
+id: coding-agent
+name: Coding Agent Orchestrator
+description: >
+  Orchestrates Claude Code sessions with smart auto-response rules.
+  Automatically handles routine questions and forwards important decisions
+  to the user.
+
+instructions: |
+  You are a coding agent orchestrator. You manage Claude Code sessions
+  via the claude-code plugin tools.
+
+  ## Auto-response rules
+
+  When a Claude Code session asks a question (🔔 wake event), analyze the
+  question and decide whether to auto-respond or forward to the user:
+
+  ### Auto-respond (use claude_respond immediately):
+  - Permission requests for file reads, writes, or bash commands
+    → Respond: "Yes, proceed."
+  - Confirmation prompts like "Should I continue?" or "Do you want me to apply these changes?"
+    → Respond: "Yes, continue."
+  - Questions about which approach to take when only one is reasonable
+    → Respond with the obvious choice
+  - Requests for clarification about the codebase (file locations, conventions)
+    → Respond with the info if you know it, or "Use your best judgment."
+
+  ### Forward to user (relay the question to the chat):
+  - Architecture decisions (e.g. "Should I use Redis or PostgreSQL for caching?")
+  - Destructive operations (e.g. "Should I delete the old migration files?")
+  - Ambiguous requirements (e.g. "The spec doesn't mention error handling — what should I do?")
+  - Budget or scope changes (e.g. "This will require refactoring 15 files — should I proceed?")
+  - Anything involving credentials, secrets, or production environments
+
+  ## Workflow
+
+  1. User sends a coding task → launch a multi-turn session:
+     claude_launch(prompt: "<task>", multi_turn: true, channel: "<origin>")
+
+  2. Session runs in background. Monitor via wake events.
+
+  3. On 🔔 wake event → read the question with claude_output, then:
+     - If auto-respond rule matches → claude_respond(session, answer)
+     - If forward rule matches → relay the question to the user
+
+  4. On user reply to a forwarded question → claude_respond with their answer
+
+  5. On ✅ completion → summarize the result and notify the user
+
+  ## Important
+
+  - Always use multi_turn: true for tasks that may need follow-up
+  - Always pass the channel parameter to maintain notification routing
+  - Never auto-respond to questions about production deployments
+  - When in doubt, forward to the user — it's better to ask than to guess
+```
+
+### How it works
+
+This skill demonstrates the key architectural principle: **Claude Code Plugin provides the transport, skills provide the brain.**
+
+| Layer | Responsibility |
+|---|---|
+| **Claude Code Plugin** (this plugin) | Spawn sessions, stream output, deliver `🔔`/`↩️` notifications, fire wake events |
+| **Skill** (e.g. `coding-agent`) | Decide what to auto-respond, what to forward, how to summarize results |
+| **User** | Receives forwarded questions, provides high-level instructions |
+
+The same Claude Code Plugin plugin can power completely different workflows — a code review skill, a CI/CD skill, a documentation skill — simply by swapping the skill definition. The plugin itself remains a generic, reusable transport layer.
+
+---
+
+## Development
+
+### Project Structure
+
+```
+claude-code/
+├── index.ts                    # Plugin entry point (register function)
+├── openclaw.plugin.json        # Plugin manifest and config schema
+├── package.json                # Dependencies
+├── src/
+│   ├── types.ts                # TypeScript interfaces
+│   ├── shared.ts               # Global state, helpers, formatting
+│   ├── session.ts              # Session class (SDK wrapper)
+│   ├── session-manager.ts      # Session pool management
+│   ├── notifications.ts        # NotificationRouter
+│   ├── gateway.ts              # RPC method registration
+│   ├── tools/
+│   │   ├── claude-launch.ts    # claude_launch tool
+│   │   ├── claude-sessions.ts  # claude_sessions tool
+│   │   ├── claude-output.ts    # claude_output tool
+│   │   ├── claude-fg.ts        # claude_fg tool
+│   │   ├── claude-bg.ts        # claude_bg tool
+│   │   ├── claude-kill.ts      # claude_kill tool
+│   │   ├── claude-respond.ts   # claude_respond tool
+│   │   └── claude-stats.ts     # claude_stats tool
+│   └── commands/
+│       ├── claude.ts           # /claude command
+│       ├── claude-sessions.ts  # /claude_sessions command
+│       ├── claude-fg.ts        # /claude_fg command
+│       ├── claude-bg.ts        # /claude_bg command
+│       ├── claude-kill.ts      # /claude_kill command
+│       ├── claude-resume.ts    # /claude_resume command
+│       ├── claude-respond.ts   # /claude_respond command
+│       └── claude-stats.ts     # /claude_stats command
+└── docs/
+    └── plans/                  # Design documents
+```
+
+### Dependencies
+
+| Package | Purpose |
+|---|---|
+| `@anthropic-ai/claude-agent-sdk` | Claude Code SDK — the `query()` function that powers each session. |
+| `@sinclair/typebox` | JSON Schema type builder for tool parameter definitions. |
+| `nanoid` | Generates short unique session IDs (8 characters). |
+
+### Key design decisions
+
+1. **Foreground is per-channel, not per-session.** Multiple channels can watch the same session simultaneously, and one channel can have multiple sessions in foreground.
+
+2. **Multi-turn uses `AsyncIterable` prompts.** The `MessageStream` class implements `Symbol.asyncIterator` to feed user messages into the SDK's `query()` function as an async generator, keeping the session alive across turns.
+
+3. **Persisted sessions survive GC.** When a session is garbage-collected (1 hour after completion), its Claude session ID is retained in a separate `persistedSessions` map so it can be resumed later. Entries are stored under three keys (internal ID, name, Claude UUID) for flexible lookup.
+
+4. **Notifications use CLI shelling.** Since the plugin API doesn't expose a runtime `sendMessage` method, outbound notifications go through `openclaw message send` via `child_process.execFile`.
+
+5. **Metrics are in-memory only.** Session metrics are aggregated in the `SessionManager` and reset on service restart. They are not persisted to disk. Cost data is tracked internally but not exposed in any user-facing output.
+
+6. **Waiting-for-input uses dual detection.** End-of-turn detection (when a multi-turn result resolves) is the primary signal, backed by a 15-second safety-net timer for edge cases. A `waitingForInputFired` flag prevents duplicate wake events.
+
+7. **Channel `"unknown"` falls through.** If `channelId` is `"unknown"`, the notification system explicitly falls through to `fallbackChannel` rather than attempting delivery to an invalid destination.
+
+### Adding a new tool or command
+
+1. Create a new file under `src/tools/` or `src/commands/`.
+2. Export a `registerXxxTool(api)` or `registerXxxCommand(api)` function.
+3. Import and call it in `index.ts` inside the `register()` function.
+
+### Service lifecycle
+
+- **`start()`** — Creates `SessionManager` and `NotificationRouter`, wires them together, starts the long-running reminder check interval (60s), and starts a GC interval (5 min).
+- **`stop()`** — Stops the notification router, kills all active sessions, clears intervals, and nulls singletons.
+
+---
+
+## License
+
+See the project repository for license information.