Dev Harness

README

# OpenClaw Dev Harness 🔧

An isolated development environment for building and debugging [OpenClaw](https://github.com/openclaw/openclaw) extensions — plugins, hooks, and skills.

## What is this?

OpenClaw is an AI agent framework. This skill sets up an isolated `--dev` environment so you can build extensions without touching your production setup.

Three extension types:
- **Plugins** — Gateway-resident code (RPC methods, CLI commands, services, agent tools, channels)
- **Hooks** — Event-driven TypeScript handlers (command events, agent lifecycle, gateway startup)
- **Skills** — SKILL.md-based knowledge extensions that teach agents new capabilities

## Quick Start

```bash
# 1. Set up isolated dev environment
bash scripts/setup-harness.sh

# 2. Start dev gateway (terminal 1)
bash scripts/dev-gateway.sh

# 3. Open TUI (terminal 2)
bash scripts/dev-tui.sh

# 4. Scaffold a new plugin
bash scripts/scaffold-extension.sh my-plugin --type plugin
```

## Installation

### As an agent skill

Drop this folder into any of these locations:

| Agent | Path |
|-------|------|
| OpenClaw | `~/.openclaw/skills/openclaw-dev-harness/` |
| Codex CLI | `~/.agents/skills/openclaw-dev-harness/` |
| Claude Code | `.claude/skills/openclaw-dev-harness/` |

Or install via [ClawHub](https://clawhub.com):
```bash
clawhub install openclaw-dev-harness
```

### Manual

```bash
git clone https://github.com/lekt9/openclaw-dev-harness.git
cd openclaw-dev-harness
bash scripts/setup-harness.sh
```

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/setup-harness.sh` | Initialize the isolated dev environment |
| `scripts/dev-gateway.sh` | Start gateway in dev mode with verbose logging |
| `scripts/dev-tui.sh` | Connect TUI to dev gateway |
| `scripts/scaffold-extension.sh` | Scaffold a new plugin, hook, or skill |
| `scripts/debug-session.sh` | Collect diagnostics from dev environment |

## Architecture

The `--dev` flag isolates all state under `~/.openclaw-dev/`:

```
~/.openclaw-dev/
├── workspace/
│   ├── extensions/    ← Your plugins go here
│   ├── hooks/         ← Your hooks go here
│   └── skills/        ← Your skills go here
├── openclaw.json      ← Dev config
└── credentials/       ← Auth profiles
```

Gateway runs on port 19001 (configurable) — completely separate from your production instance.

## References

Detailed API docs included:

- **[Plugin API](references/plugin-api.md)** — Registration methods, config schema, testing patterns
- **[Hooks API](references/hooks-api.md)** — Event types, handler signatures, discovery
- **[Testing](references/testing.md)** — Test suites, env vars, stream debugging

## Example: Create a Plugin

```bash
# Scaffold it
bash scripts/scaffold-extension.sh hello-world --type plugin

# Edit ~/.openclaw-dev/workspace/extensions/hello-world/index.ts
# Then restart gateway
openclaw --dev gateway restart

# Test it
openclaw --dev gateway call hello-world.status --params '{}'
```

## TUI Shortcuts

| Action | Key |
|--------|-----|
| Send message | Enter |
| Stop run | Esc |
| Model picker | Ctrl+L |
| Agent picker | Ctrl+G |
| Toggle tool output | Ctrl+O |
| Toggle thinking | Ctrl+T |

## Links

- [OpenClaw Docs](https://docs.openclaw.ai)
- [OpenClaw GitHub](https://github.com/openclaw/openclaw)
- [ClawHub Skills](https://clawhub.com)
- [Discord](https://discord.gg/clawd)

## License

MIT