Integration

Openclawgsd

Name: Openclawgsd
Rating: 3.5 (1 reviews)
Author: mitgor

By mitgor 👁 145 views ▲ 0 votes

openclaw plugin that delegates multi-step tasks to Claude Code + GSD via a pty-driven TUI bridge. Auto-approve, fail-closed security gates, per-task ephemeral sessions.

GitHub

Install

npm install -g

Configuration Example

{
  "channels": ["cli"],
  "peers": ["local"],
  "projectRoots": ["/absolute/path/to/your/trusted/project"],
  "envAllowlist": ["PATH", "HOME", "USER", "TERM", "LANG", "SHELL", "TMPDIR"]
}

README

# openclawgsd

> openclaw + Claude Code + GSD — automated multi-step task delegation via PTY

---

```
╔══════════════════════════════════════════════════════════════════════╗
║  !! DANGER: --dangerously-skip-permissions ENABLED !!               ║
║                                                                      ║
║  This skill spawns `claude --dangerously-skip-permissions` and       ║
║  auto-approves every tool call (file writes, shell commands, git     ║
║  operations) WITHOUT user confirmation. Security depends entirely    ║
║  on the allowlists you configure — channel, peer, and project-root. ║
║                                                                      ║
║  DO NOT install this skill unless you:                               ║
║    1. Understand what --dangerously-skip-permissions does            ║
║    2. Have configured strict allowlists (see Security Model below)   ║
║    3. Are running on a machine you control                           ║
║    4. Have reviewed the security invariants (SEC-01..09)             ║
║                                                                      ║
║  This is NOT safe for untrusted networks, shared machines, or        ║
║  always-on devices reachable from external channels (WhatsApp,       ║
║  Telegram, Signal, etc.) without explicit allowlist configuration.   ║
╚══════════════════════════════════════════════════════════════════════╝
```

---

## What It Does

openclawgsd is an openclaw workspace skill that lets an openclaw user delegate any
non-trivial multi-step coding task to Claude Code + GSD by driving the real Claude
Code interactive TUI through a pseudo-terminal. When you ask openclaw to "refactor
the pty driver" or "implement the auth service step by step", openclawgsd classifies
the request, enforces security gates, spawns a fresh `claude` session with
`--dangerously-skip-permissions` inside your project directory, types the appropriate
GSD slash command into the live TUI, streams the output back to your terminal, and
writes a structured summary to openclaw session memory when the session ends. You
never leave openclaw; complex work runs unattended in a fresh, isolated Claude Code
session.

## How It Works

```
openclaw user message
        |
        v
 Pre-LLM Interceptor ---- classify() ---- score >= threshold?
        |                                         |
        | (ambiguous)                             | (hard route)
        v                                         |
 openclaw agent LLM                               |
        | claude_delegate({task})                 |
        v                                         v
 +-------------------------------------------------+
 |           openclawgsd skill                     |
 |                                                 |
 |  Classifier (shared rules, pure function)       |
 |        |                                        |
 |        v                                        |
 |  Security Gates (SEC-01..09)                   |
 |  - channel allowlist                           |
 |  - peer allowlist                              |
 |  - project-root allowlist                      |
 |  - git branch isolation                        |
 |  - env scrub                                   |
 |  - lockfile                                    |
 |        |                                        |
 |        v                                        |
 |  Session Orchestrator (FSM)                    |
 |  idle -> spawning -> injecting -> running       |
 |       -> exiting -> disposed                   |
 |        |                                        |
 |        v                                        |
 |  PTY Driver                                    |
 |  (spawn claude --dangerously-skip-permissions) |
 |        |                 |                      |
 |        | keystrokes      | stdout (ANSI)        |
 |        |                 v                      |
 |        |     Output Relay -> openclaw transport |
 |        |                     -> user terminal   |
 |        v                                        |
 |  [claude exits]                                |
 |        |                                        |
 |        v                                        |
 |  Memory Writer                                 |
 |  (git diff, commits, GSD phase, status)        |
 |  -> openclaw session memory                    |
 +-------------------------------------------------+
```

See [docs/architecture.md](docs/architecture.md) for the full component diagram and
FSM state diagram.

## Prerequisites

- **Node.js 24+** — `node --version` must show v24 or later
- **claude CLI** — installed and authenticated: `npm install -g @anthropic-ai/claude-code && claude login`
- **GSD** — installed at `~/.claude/get-shit-done/` (the GSD slash-command suite)
- **openclaw** — the openclaw runtime, configured with at least one workspace

## Installation

**1. Install the package into your openclaw skill workspace:**

```bash
# From your openclaw workspace directory
npm install openclawgsd
# or via a path reference for local development:
# npm install /path/to/openclawgsd
```

**2. Copy the example config:**

```bash
cp node_modules/openclawgsd/config/delegation.example.json config/delegation.json
```

**3. Edit `config/delegation.json` — this is your security perimeter:**

```json
{
  "channels": ["cli"],
  "peers": ["local"],
  "projectRoots": ["/absolute/path/to/your/trusted/project"],
  "envAllowlist": ["PATH", "HOME", "USER", "TERM", "LANG", "SHELL", "TMPDIR"]
}
```

All three allowlists are required and must be non-empty.
`projectRoots` must contain absolute paths starting with `/`.

**4. Register the skill in your openclaw workspace** by placing `skills/openclawgsd/SKILL.md`
where openclaw's skill loader will find it (see openclaw workspace skill documentation).

**5. Run the self-test to verify all prerequisites are met:**

```bash
npx openclawgsd-self-test
# or after build:
node dist/bin/openclawgsd-self-test.js
```

The self-test checks:
- `@homebridge/node-pty-prebuilt-multiarch` native addon loads without compiler toolchain
- `claude` binary is present on PATH (auth state is your responsibility — run `claude status`)
- GSD is installed at `~/.claude/get-shit-done/`

**The self-test must pass before you enable the skill in openclaw.**

## Usage

Once installed, openclaw's agent LLM can call the `claude_delegate` tool, or the
pre-LLM interceptor will hard-route high-confidence delegation requests automatically.

**Example prompts that trigger delegation:**

```
"Refactor the authentication module to use JWT with refresh token rotation"
"Implement a rate limiter for the API endpoints step by step"
"Fix the race condition in the pty driver and add regression tests"
"Build the entire admin dashboard according to the spec in docs/admin.md"
```

**What the openclaw agent sees (tool description):**

```
claude_delegate(task: string, context?: string) -> DelegationOutcome

Delegates a complex, multi-step coding task to Claude Code + GSD running in
a fully automated PTY session with --dangerously-skip-permissions.

Use this tool when:
- The task has multiple implementation steps (build, refactor, implement, fix, add)
- The task references specific files or directories (@path mentions)
- The user asks for a step-by-step plan + execution
- The task is complex enough to benefit from GSD's planning workflow

Do NOT use this tool for:
- Simple questions or explanations
- Single-file edits you can do directly
- Tasks on channels other than cli (this tool refuses non-terminal channels)
```

**Session flow:**

1. Delegation is classified and security-gated
2. A fresh `claude` session spawns in an isolated git branch `claw/delegation/<uuid>`
3. GSD's `/gsd-new-project --auto` is typed into the TUI with the task text
4. Output streams as text blocks to your openclaw terminal
5. On exit, a structured summary is written to openclaw session memory:
   ```json
   {
     "task": "...",
     "filesChanged": ["src/auth.ts", "src/auth.test.ts"],
     "commits": ["abc123 feat: add JWT auth"],
     "gsdPhaseReached": "phase-2",
     "status": "success",
     "durationMs": 45200
   }
   ```
6. You can ask openclaw follow-up questions and it will remember the delegation

## Security Model

openclawgsd's security model is defense-in-depth. All nine invariants (SEC-01..09)
must be in place simultaneously — fail-closed, not fail-open (SEC-09).

**SEC-01 — Channel allowlist**
Only openclaw channels listed in `config/delegation.json → channels` can trigger
delegation. Default is `["cli"]` — the local terminal only. WhatsApp, Telegram,
Discord, and other network channels are NOT on the allowlist by default and must be
explicitly opted in. A poisoned inbound message from an un-allowlisted channel is
refused before any spawning occurs.

**SEC-02 — Peer allowlist**
Even on allowed channels, only senders listed in `peers` can trigger delegation.
Default is `["local"]`. This prevents drive-by delegation from arbitrary contacts
on an always-on device.

**SEC-03 — Project-root allowlist**
The delegated `claude` spawns only inside directories listed in `projectRoots`.
The cwd is resolved via `realpath` and checked against the allowlist before any spawn.
Symlink escape attempts are detected and refused.

**SEC-04 — Git branch isolation**
When the project is a git repo, delegation runs on a dedicated branch
`claw/delegation/<uuid>`. A git wrapper blocks `git push` for the duration of the
session. Changes are committed but never pushed — the user reviews and pushes manually.

**SEC-05 — Environment scrub**
Only the env vars listed in `envAllowlist` are passed to the spawned `claude` process.
All others (`AWS_*`, `GITHUB_TOKEN`, `OPENAI_API_KEY`, `*_SECRET`, etc.) are stripped.
This prevents secret exfiltration via the spawned session.

**SEC-06 — No process.chdir**
`process.chdir` is forbidden in skill code. Working directory is always

... (truncated)

integration