Ralph-orchestrator ralph-tools

Shared tool commands for interact, skill, and output format reference during Ralph orchestration

install

source · Clone the upstream repo

git clone https://github.com/mikeyobrien/ralph-orchestrator

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/mikeyobrien/ralph-orchestrator "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/ralph-tools" ~/.claude/skills/mikeyobrien-ralph-orchestrator-ralph-tools && rm -rf "$T"

manifest: .claude/skills/ralph-tools/SKILL.md

source content

Ralph Tools

Quick reference for shared

ralph tools

commands used during orchestration.

Interact Commands

ralph tools interact progress "message"

Send a non-blocking progress update via the configured RObot (Telegram).

Skill Commands

ralph tools skill list
ralph tools skill load <name>

List available skills or load a specific skill by name.

Wave Commands

Dispatch multiple events as a wave for parallel hat execution:

ralph wave emit <topic> --payloads "item1" "item2" "item3"

Each payload becomes a separate event tagged with a shared

wave_id

. The loop runner detects wave events and spawns parallel backend instances (up to the hat's

concurrency

limit).

When to use: When a hat's configuration has

concurrency > 1

, use wave dispatch to send N items for parallel processing instead of N sequential iterations.

Constraints:

Cannot be used inside a wave worker (
```
RALPH_WAVE_WORKER=1
```
blocks it)
Wave workers emit results via
```
ralph emit
```
, not
```
ralph wave emit
```

Memory Commands

ralph tools memory add "content" -t pattern --tags tag1,tag2
ralph tools memory list [-t type] [--tags tags]
ralph tools memory search "query" [-t type] [--tags tags]
ralph tools memory prime --budget 2000    # Output for context injection
ralph tools memory show <mem-id>
ralph tools memory delete <mem-id>

Memory types:

Type	Flag	Use For
pattern	`-t pattern`	"Uses barrel exports", "API routes use kebab-case"
decision	`-t decision`	"Chose Postgres over SQLite for concurrent writes"
fix	`-t fix`	"ECONNREFUSED on :5432 means run docker-compose up"
context	`-t context`	"ralph-core is shared lib, ralph-cli is binary"

Memory ID format:

mem-{timestamp}-{4hex}

(e.g.,

mem-1737372000-a1b2

)

NEVER use echo/cat to write tasks or memories — always use CLI tools.

When to Search Memories

Search BEFORE starting work when:

Entering unfamiliar code area →
```
ralph tools memory search "area-name"
```

Encountering an error →

ralph tools memory search -t fix "error message"

Making architectural decisions →

ralph tools memory search -t decision "topic"

Something feels familiar → there might be a memory about it

Search strategies:

Start broad, narrow with filters:

search "api"

→

search -t pattern --tags api

Check fixes first for errors:
```
search -t fix "ECONNREFUSED"
```
Review decisions before changing architecture:
```
search -t decision
```

When to Create Memories

Create a memory when:

You discover how this codebase does things (pattern)
You make or learn why an architectural choice was made (decision)
You solve a problem that might recur (fix)
You learn project-specific knowledge others need (context)
Any non-zero command, missing dependency/skill, or blocked step (fix + task if unresolved)

Do NOT create memories for:

Session-specific state (use tasks instead)
Obvious/universal practices
Temporary workarounds

Failure Capture (Generic Rule)

If any command fails (non-zero exit), or you hit a missing dependency/skill, or you are blocked:

Record a fix memory with the exact command, error, and intended fix.
Open or reopen a task if it won't be resolved in the same iteration.

ralph tools memory add \
  "failure: cmd=<command>, exit=<code>, error=<message>, next=<intended fix>" \
  -t fix --tags tooling,error-handling

ralph tools task ensure "Fix: <short description>" --key fix:<short-key> -p 2

Discover Available Tags

Before searching or adding, check what tags already exist:

ralph tools memory list
grep -o 'tags: [^|]*' .agent/memories.md | sort -u

Reuse existing tags for consistency. Common tag patterns:

Component names:
```
api
```
,
```
auth
```
,
```
database
```
,
```
cli
```
Concerns:
```
testing
```
,
```
performance
```
,
```
error-handling
```
Tools:
```
docker
```
,
```
postgres
```
,
```
redis
```

Memory Best Practices

Be specific: "Uses barrel exports in each module" not "Has good patterns"
Include why: "Chose X because Y" not just "Uses X"
One concept per memory: Split complex learnings
Tag consistently: Reuse existing tags when possible

Decision Journal

Use

.ralph/agent/decisions.md

to capture consequential decisions and their confidence scores. Follow the template at the top of the file and keep IDs sequential (DEC-001, DEC-002, ...).

Confidence thresholds:

>80: Proceed autonomously.
50-80: Proceed, but document the decision in
```
.ralph/agent/decisions.md
```
.
<50: Choose the safest default and document the decision in
```
.ralph/agent/decisions.md
```
.

Template fields:

Decision
Chosen Option
Confidence (0-100)
Alternatives Considered
Reasoning
Reversibility
Timestamp (UTC ISO 8601)

Output Formats

All commands support

--format

```
table
```
(default) - Human-readable
```
json
```
- Machine-parseable
```
quiet
```
- IDs only (for scripting)
```
markdown
```
- Memory prime only

NEVER use echo/cat to write tasks or memories — always use CLI tools.