vybe-agent-patterns

name: vybe-agent-patterns description: | Crash-safe continuity for autonomous agents. Use when building agents that need to resume work after interruption, track progress across sessions, coordinate multiple workers, or persist memory/artifacts durably. Triggers: "resume task", "agent crash", "checkpoint progress", "multi-agent", "work queue", "autonomous loop". NOT for: single-shot tasks completing in one session, tasks without crash recovery, non-autonomous workflows requiring human approval.

Vybe Agent Patterns

Patterns and commands for using vybe as the durable state layer in autonomous agent workflows.

Quick Reference

MUST (BLOCKING):

• Agent MUST have a stable identity: set default_agent in ~/.config/vybe/config.yaml, VYBE_AGENT env var, or --agent flag
• Resume MUST be called at session start before accessing focus task
• Task closure in autonomous loops MUST use vybe done <id> (or vybe block <id> --reason ...)
• --request-id is OPTIONAL and omitted by default. A freshly-generated per-call id is identical to omitting it (vybe auto-generates one either way — both give at-least-once). Pass a STABLE --request-id ONLY to retry the exact same operation (or group a known set of ops). Never generate a fresh id per call.

Install (BLOCKING)

# MUST install vybe before using patterns
go install github.com/dotcommander/vybe/cmd/vybe@latest

# MUST install hooks for automatic Claude Code integration
vybe hook install --claude

# MUST set stable agent identity. Easiest: set it once in config so every
# command can omit --agent:
#   echo 'default_agent: claude' >> ~/.config/vybe/config.yaml
# Or export an env var (add to ~/.bashrc or ~/.zshrc):
export VYBE_AGENT=claude

# Verify setup
vybe status | jq -e '.success and .data.db.ok' > /dev/null && echo "ok"

If vybe status fails: Check ~/.config/vybe/config.yaml exists and db_path is writable.

Config lookup order (first wins): ~/.config/vybe/config.yaml → /etc/vybe/config.yaml → ./config.yaml

Core Concepts

Identity and Idempotency

Every agent needs a stable name. Set it once and forget it.

# Set agent identity once — used by all subsequent commands. Either:
#   ~/.config/vybe/config.yaml:  default_agent: claude
# or:
export VYBE_AGENT=claude

# With identity set, writes need no --request-id at all:
vybe task create --title "Implement auth" --desc "Add JWT middleware"

Identity resolution order: --agent flag → VYBE_AGENT env var → config.yaml: default_agent. Setting default_agent (or VYBE_AGENT) once lets you drop --agent from every command.

Request IDs (idempotency): --request-id is optional and omitted by default. vybe auto-generates a unique id for every mutation, so a freshly-generated per-call id (done_$(date +%s), $RANDOM, etc.) is behaviorally identical to omitting it — both give at-least-once execution, and dedup only fires when the SAME (agent, request-id, command) recurs. Pass a STABLE --request-id ONLY when you intend to retry the exact same operation and want the original result replayed. Do not invent a new id on each call.

Resume Cycle (MUST Follow)

The fundamental pattern: resume -> work -> note -> done -> resume.

export VYBE_AGENT=claude   # or set default_agent in config.yaml

# 1. Get context (advances cursor, returns focus task + memory + events)
BRIEF=$(vybe resume)

# 2. MUST check success before proceeding
if [ "$(echo "$BRIEF" | jq -r '.success')" != "true" ]; then
  echo "Resume failed: $(echo "$BRIEF" | jq -r '.error')"
  exit 1
fi

# 3. Extract focus task ID (MUST use jq for JSON parsing)
TASK_ID=$(echo "$BRIEF" | jq -r '.data.focus_task_id // ""')

# 4. MUST check for null/empty before proceeding
if [ -z "$TASK_ID" ] || [ "$TASK_ID" = "null" ]; then
  echo "No focus task available"
  exit 0
fi

# 5. Do work, log progress
vybe note "$TASK_ID" "Implemented JWT validation"

# 6. Close task in one atomic call (with an optional final note)
vybe done "$TASK_ID" --note "JWT middleware shipped and tested"

BLOCKING: Always check .data.focus_task_id for null/empty. Resume returns empty focus when no work available.

Read-only peek at the current focus: vybe focus prints the focus task without advancing the cursor — handy for a quick "what am I on?" check between steps.

Response paths: Use data.focus_task_id for the task ID string. Use data.brief.task for the full task object.

Memory Scopes

Memory persists key-value pairs at four scopes:

export VYBE_AGENT=claude

# Save a discovery
vybe remember "api_base=https://staging.example.com" \
  --scope project --scope-id "$PROJECT_DIR"

# Read it back (any session)
vybe memory get --key api_base --scope project --scope-id "$PROJECT_DIR"

vybe remember "k=v" takes the same --scope/--scope-id/--kind/--pin flags as vybe memory set --key k --value v ... — it's just the terse form. Use --kind directive for behavioral rules, --pin for durable strategic memory.

When to Use Vybe (BLOCKING Decision)

MUST use vybe when:

• Multi-step tasks span sessions or risk interruption
• Multiple agents work on the same project concurrently
• Progress must survive crashes, context resets, or session limits
• Task queues need deterministic focus selection
• Artifacts (generated files, reports) need linking to the task that produced them
• Cross-session memory is needed (facts, decisions, checkpoints)

Skip vybe when:

• Single-shot tasks that complete in one session
• No crash recovery needed
• No coordination between agents
• Ephemeral work with no continuity requirement

If uncertain: default to using vybe. Overhead is minimal; lost continuity is catastrophic.

JSON Response Envelope (BLOCKING)

MUST check .success field before using .data.

// Success
{"schema_version": "v1", "success": true, "data": {...}}

// Error
{"schema_version": "v1", "success": false, "error": "..."}

Resume response structure:

{
  "schema_version": "v1",
  "success": true,
  "data": {
    "agent_name": "claude",
    "old_cursor": 42,
    "new_cursor": 58,
    "focus_task_id": "task_1234567890_a3f9",
    "focus_project_id": "project_1234567890_b2e8",
    "deltas": [...],
    "brief": {
      "task": {...},
      "project": {...},
      "relevant_memory": [...],
      "recent_events": [...],
      "artifacts": [...]
    }
  }
}

Push response structure:

{
  "schema_version": "v1",
  "success": true,
  "data": {
    "event_id": 123,
    "memories": [{"key": "...", "canonical_key": "...", "reinforced": false}],
    "artifacts": [{"artifact_id": "artifact_...", "file_path": "..."}],
    "task_status": {"task_id": "task_...", "status": "completed"}
  }
}

Claude Code Integration

Automatic (hooks)

After vybe hook install --claude, Claude Code automatically:

• SessionStart: Injects task context, memory, and recent events
• UserPromptSubmit: Logs prompts for cross-session continuity
• PostToolUseFailure: Records failed tool calls for recovery
• TaskCompleted: Marks tasks complete and logs lifecycle signals
• PreCompact: Runs garbage collection and event maintenance
• SessionEnd: Runs garbage collection

Proactive usage in CLAUDE.md

Add to your project's CLAUDE.md to teach Claude Code to use vybe:

## Vybe Integration

When working on multi-step tasks, use vybe for durable state:

# Store discoveries that should persist across sessions
vybe remember "<key>=<value>" --scope task --scope-id <task_id>

# Log a progress checkpoint
vybe note <task_id> "<what happened>"

# Mark a task done (optionally with a closing note)
vybe done <task_id> --note "<summary>"

# When several writes must land together, use push (one atomic call)
vybe push --json '{
  "task_id": "<task_id>",
  "event": {"kind": "progress", "message": "<what happened>"},
  "artifacts": [{"file_path": "<path>"}]
}'

Patterns

Worker Loop (Before/After)

Before (fragile):

#!/usr/bin/env bash
# Missing request IDs, no null checks, no error handling
TASK_ID=$(vybe resume --peek | jq '.data.brief.task.id')
vybe task set-status --id "$TASK_ID" --status completed

After (crash-safe):

#!/usr/bin/env bash
set -euo pipefail
export VYBE_AGENT="${VYBE_AGENT:-worker-001}"

while true; do
  RESUME=$(vybe resume)

  if [ "$(echo "$RESUME" | jq -r '.success')" != "true" ]; then
    echo "Resume failed: $(echo "$RESUME" | jq -r '.error')"
    exit 1
  fi

  TASK_ID=$(echo "$RESUME" | jq -r '.data.focus_task_id // ""')

  if [ -z "$TASK_ID" ] || [ "$TASK_ID" = "null" ]; then
    echo "No work available"
    sleep 10
    continue
  fi

  # Do work...
  vybe note "$TASK_ID" "Processing..."

  vybe done "$TASK_ID"
done

Key improvements: stable identity, success check, null checks, resume instead of brief, explicit terminal status via vybe done. No per-call request-id noise — vybe auto-generates ids, and each loop pass is a genuinely new operation.

Task Decomposition (Before/After)

Before (brittle):

# No request IDs, hardcoded task IDs, no null checks
vybe task create --title "Step 1"
vybe task create --title "Step 2"

After (clean):

export VYBE_AGENT="${VYBE_AGENT:-planner}"

# Create parent task — no --request-id needed
PARENT=$(vybe task create \
  --title "Ship v2.0" --desc "Release milestone" | jq -r '.data.task.id')

# Create subtasks
STEP1=$(vybe task create \
  --title "Write migration" --desc "Schema changes for v2" | jq -r '.data.task.id')

STEP2=$(vybe task create \
  --title "Update API handlers" --desc "New endpoints" | jq -r '.data.task.id')

Key improvements: stable identity, jq extraction, no request-id noise.

Stable request-ids for safe batch retry (optional): if this script may be re-run after a partial failure and you want each task create to be idempotent (no duplicate tasks on the second run), give each a fixed, content-derived id that is identical across runs — not a fresh timestamp:

# Re-running this exact block replays the original tasks instead of duplicating them.
vybe task create --request-id "v2_migration"   --title "Write migration"     --desc "Schema changes for v2"
vybe task create --request-id "v2_api_handlers" --title "Update API handlers" --desc "New endpoints"

The point is the id stays the SAME on retry. A date +%s-based id changes every run and would dedupe nothing — that's the cargo-cult to avoid.

Crash-Safe Checkpoint (Before/After)

Before (loses progress on crash):

# In-memory progress counter, lost on restart
PROGRESS_COUNT=0
for item in "${ITEMS[@]}"; do
  process "$item"
  PROGRESS_COUNT=$((PROGRESS_COUNT + 1))
done

After (resume from exact checkpoint):

export VYBE_AGENT="${VYBE_AGENT:-worker}"

# Before expensive operation, record intent
vybe remember "current_operation=migrating_table_users" \
  --scope task --scope-id "$TASK_ID"

# Do the work...

# After success, clear checkpoint
vybe remember "current_operation=completed" \
  --scope task --scope-id "$TASK_ID"

# On resume, check checkpoint
CHECKPOINT=$(vybe memory get --key current_operation \
  --scope task --scope-id "$TASK_ID" | jq -r '.data.value // ""')

if [ "$CHECKPOINT" = "migrating_table_users" ]; then
  # Resume from checkpoint — operation was started but not completed
  echo "Resuming incomplete migration..."
fi

Key improvements: persistent checkpoint state, resume detection, idempotent operations.

Examples

Multi-Agent Research Pipeline

#!/usr/bin/env bash
# Coordinator agent creates tasks, worker agents claim and execute

# Coordinator: decompose research into tasks
export VYBE_AGENT=research-coordinator

vybe task create \
  --title "Gather academic papers" \
  --desc "Search arxiv.org for relevant papers on topic X"

vybe task create \
  --title "Extract citations" \
  --desc "Parse PDFs and extract citation graphs"

vybe task create \
  --title "Synthesize findings" \
  --desc "Aggregate results into summary report"

# Worker agent: claim and execute
export VYBE_AGENT=research-worker-01

RESUME=$(vybe resume)
TASK_ID=$(echo "$RESUME" | jq -r '.data.focus_task_id // ""')

if [ -n "$TASK_ID" ] && [ "$TASK_ID" != "null" ]; then
  vybe task begin --id "$TASK_ID"

  # Execute work...

  # push when the artifact link must land with the event atomically
  vybe push --json \
    "{\"task_id\":\"$TASK_ID\",\"artifacts\":[{\"file_path\":\"./output/papers.json\"}]}"

  vybe done "$TASK_ID"
fi

Session-Spanning Code Refactor

# Session 1: Start refactor, record progress
export VYBE_AGENT=refactor-agent

TASK_ID=$(vybe task create \
  --title "Extract payment logic" \
  --desc "Move payment code to separate module" | jq -r '.data.task.id')

vybe remember "files_refactored=checkout.go,payment.go" \
  --scope task --scope-id "$TASK_ID"

# Session crashes or context resets...

# Session 2: Resume from checkpoint
RESUME=$(vybe resume)
TASK_ID=$(echo "$RESUME" | jq -r '.data.focus_task_id // ""')
FILES=$(echo "$RESUME" | jq -r '.data.brief.relevant_memory[] | select(.key=="files_refactored") | .value')
echo "Resuming refactor of: $FILES"

Command Cheatsheet

# Set identity once (config.yaml: default_agent, or env var)
export VYBE_AGENT=claude

# Task lifecycle (sugar verbs — no --request-id needed)
vybe task create --title T --desc D
vybe task begin  --id ID
vybe note  ID "progress message"            # record a progress event
vybe done  ID [--note "closing summary"]    # complete (atomic)
vybe block ID --reason "..." [--failure]    # block; --failure → resume skips it
vybe task list
vybe task get --id ID
# Verbose equivalent of done/block: vybe task set-status --id ID --status completed|blocked

# Memory (--scope-id optional for task/project when a focus is set; required for agent scope)
vybe remember "K=V" --scope S --scope-id SI  # terse memory write (--kind, --pin also accepted)
vybe memory get  --key K --scope S --scope-id SI
vybe memory list --scope S --scope-id SI

# Push (atomic multi-op: event + memory + artifacts + status together). Use for
# genuine batches, or for reasoning/metadata events (e.g. kind=THINK).
vybe push --json '{"task_id":"T","event":{"kind":"K","message":"M"},"artifacts":[{"file_path":"P"}]}'

# Events / artifacts (read-only)
vybe events    --task-id T
vybe artifacts --task-id T

# Context
vybe focus                                  # print current focus, read-only
vybe resume                                 # advances cursor (full brief)
vybe resume --peek                          # read-only full brief, no cursor advance
vybe status                                 # agent state
vybe status --check                         # fast health gate (exit code)

Anti-Patterns

Common Errors