Tools

Goals

Name: Goals
Rating: 3.5 (1 reviews)
Author: MrDiamondBallz

By MrDiamondBallz 👁 391 views ▲ 0 votes

Persistent, checkpointed goal-oriented task engine for OpenClaw. Set an objective, walk away, and it finishes — surviving restarts, crashes, and timeouts. Please leave your feedback!

Homepage GitHub

Install

npm install &&

Configuration Example

{
  "plugins": {
    "entries": {
      "openclaw-goals": {
        "enabled": true,
        "config": {
          "max_concurrent": 3,
          "watchdog_interval_ms": 30000,
          "stale_heartbeat_seconds": 120,
          "default_max_steps": 200,
          "max_retries": 3
        }
      }
    }
  }
}

README

# 🦞 openclaw-goals

**Persistent, checkpointed goal-oriented task engine for OpenClaw.**

Set an objective, walk away, and the agent finishes it — surviving restarts, crashes, and timeouts. Native OpenClaw plugin, no external dependencies.

## Features

- **Persistent state** — goals survive gateway restarts, worker crashes, OOM kills
- **Checkpoint-aware workers** — sub-agents write progress after every step; resume exactly where they left off
- **Automatic recovery** — watchdog re-spawns crashed workers within 30 seconds
- **Step budgeting** — prevents runaway costs with configurable step limits
- **User notification** — alerts you when a goal needs input or completes
- **CLI + Agent tools** — manage goals from chat or terminal

## Quick Start

```bash
# Install from GitHub
openclaw plugins install git+https://github.com/MrDiamondBallz/openclaw-goals

# Or local dev
cd openclaw-goals
npm install && npm run build
openclaw plugins install .
```

After install, restart the gateway: `openclaw gateway restart`

## Usage

### Via agent chat

```
You: start a goal: refactor auth middleware to JWT
Agent: ✅ Goal started! Objective: refactor auth middleware to JWT

You: goal status
Agent: 🔄 goal-auth-refactor — active — 47/200 steps — 2h ago

You: goal pause
Agent: ⏸️ Paused at step 47.

You: goal resume
Agent: ▶️ Resumed from step 47.
```

### Via CLI

```bash
openclaw goal list
openclaw goal status <goal-id>
openclaw goal cancel <goal-id>
```

## Configuration

```json
{
  "plugins": {
    "entries": {
      "openclaw-goals": {
        "enabled": true,
        "config": {
          "max_concurrent": 3,
          "watchdog_interval_ms": 30000,
          "stale_heartbeat_seconds": 120,
          "default_max_steps": 200,
          "max_retries": 3
        }
      }
    }
  }
}
```

| Option | Default | Description |
|--------|---------|-------------|
| `max_concurrent` | 3 | Goals running at once |
| `watchdog_interval_ms` | 30000 | Health check frequency |
| `stale_heartbeat_seconds` | 120 | Worker declared dead after |
| `default_max_steps` | 200 | Step budget per goal |
| `max_retries` | 3 | Recovery attempts before failure |

## Architecture

```
openclaw-goals/
├── openclaw.plugin.json    # Plugin manifest
├── package.json            # npm package
├── SKILL.md                # Agent usage docs (loaded by OpenClaw)
├── src/
│   ├── index.ts            # Plugin entry — tools + commands + lifecycle
│   ├── manager.ts          # Atomic state CRUD
│   ├── worker.ts           # Sub-agent spawn + prompt builder
│   ├── watchdog.ts         # Stale detection + recovery logic
│   └── types.ts            # Goal state schema + config types
└── goals/                  # State directory (created at runtime)
```

**Goal state** lives in `goals/goal-<id>.json` — atomic writes via temp+rename. No corruption.

**Worker** is an isolated sub-agent spawned via `api.runtime.subagent.run()` with a long timeout and the goal prompt.

**Watchdog** runs as an interval inside `gateway_start` → `gateway_stop` lifecycle hooks. It scans for stale heartbeats, re-spawns dead workers, and notifies on `awaiting_input`.

## For Developers

```bash
npm install
npm run build     # compiles src/ → dist/
npm run clean     # removes dist/
```

## How it compares

| Feature | Codex `/goal` | Claude Code | openclaw-goals |
|---------|:---:|:---:|:---:|
| Survives terminal close | ✅ | ❌ | ✅ |
| Survives gateway restart | ❌ | ❌ | ✅ |
| Background watchdog | ❌ | ❌ | ✅ |
| Native OpenClaw integration | ❌ | ❌ | ✅ |
| Step budgeting | ❌ | ❌ | ✅ |
| Pause/resume | ✅ | ✅ | ✅ |
| State persistence | file-based | memory | atomic JSON |

## Install from source

```bash
git clone https://github.com/MrDiamondBallz/openclaw-goals.git
cd openclaw-goals
npm install && npm run build
openclaw plugins install .
openclaw gateway restart
```

## License

MIT

tools