home / skills / openclaw / skills / doppleganger

doppleganger skill

safe

This skill prevents duplicate subagent sessions by checking running tasks before spawning, saving tokens and reducing lag for a single, coordinated execution.

npx playbooks add skill openclaw/skills --skill doppleganger

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

2.2 KB

---
name: doppleganger
displayName: Doppleganger
description: Prevents duplicate subagent sessions running the same task. Saves tokens and reduces lag—no more "multiple Spidermen" doing the same work.
version: 1.0.0
---

# Doppleganger

## Description

Prevents duplicate subagent sessions running the same task. Saves tokens and reduces lag—no more "multiple Spidermen" doing the same work.

# Doppleganger

**One task, one agent.** Doppleganger stops duplicate subagent sessions from running the same task. That prevents token overspend, UI lag, and the chaos of five identical "task completed" announcements.


## Usage

- The orchestrator **already runs** a duplicate check before `sessions_spawn` (see delegate rule); Doppleganger is the named skill for that behavior.
- User says: "prevent duplicate agents", "stop dopplegangers", "why are so many agents doing the same thing?"
- You want a single entry point to **check** whether a task is already running before spawning.

```bash
python3 /Users/ghost/.openclaw/workspace/skills/doppleganger/scripts/doppleganger.py check "<task string>" [--json]
python3 /Users/ghost/.openclaw/workspace/skills/doppleganger/scripts/doppleganger.py guard --task "<task>" [--json]
```

**JSON output:**

- `{"duplicate": false, "doppleganger_ok": true}` → safe to spawn.
- `{"duplicate": true, "reason": "running", "sessionId": "...", "key": "...", "doppleganger_ok": true}` → do not spawn; reply that the task is already running.

**Exit codes:** 0 = no duplicate (or check ok). 1 = error. 2 = duplicate detected.


## What it does

- **check** / **guard** — Given a task string (the same one you would pass to `sessions_spawn`), returns whether that task is already running. If yes, the orchestrator must not spawn again.
- Uses the subagent-tracker's `check-duplicate` under the hood (one source of truth for runs/sessions).


## Orchestrator

The delegate rule runs a duplicate check before every `sessions_spawn`; that check can be implemented by calling Doppleganger (or subagent-tracker `check-duplicate`) with the router's task string. If `duplicate: true`, do not call `sessions_spawn`.


## Name

"Doppleganger" = the duplicate agent doing the same thing. One Spiderman is enough.

Overview

This skill prevents duplicate subagent sessions from running the same task so you save tokens and avoid UI lag. It enforces a one-task-one-agent rule by checking whether a task string is already active before spawning another session. Use it as a gate in an orchestrator to stop redundant agents and duplicate outputs.

How this skill works

Given the exact task string you would pass to sessions_spawn, the skill runs a duplicate check and returns a JSON result indicating whether a duplicate exists. It delegates to a single source-of-truth tracker (the subagent-tracker) to determine running sessions and produces exit codes and structured output for automated decision making. If a duplicate is detected, the orchestrator should not spawn a new subagent.

When to use it

Before calling sessions_spawn to ensure only one agent handles a given task string
In orchestrator delegate rules that must avoid token overspend and redundant work
When many agents could independently start the same job and cause noise or lag
In workflows that require a single authoritative run of a task at any time

Best practices

Pass the exact, canonical task string used by the router to avoid mismatches
Run the check synchronously in the delegate rule immediately before spawn
Treat duplicate:true as authoritative and do not attempt to spawn or retry immediately
Log the returned sessionId and reason when a duplicate is found for auditing

Example use cases

Prevent five identical 'fetch-data' subagents from running concurrently
Guard scheduled tasks so only one instance processes a given dataset
Integrate into CI pipelines that spawn agents to perform one-off jobs
Reduce token costs by blocking redundant language-model work across services

FAQ

What output does the skill return when no duplicate is found?

It returns a JSON object like {"duplicate": false, "doppleganger_ok": true} and exits with code 0.

What should the orchestrator do when a duplicate is detected?

Do not call sessions_spawn. Inspect the returned sessionId/reason, notify the user if appropriate, and avoid immediate retries.