Dotcommander Vybe Vybe Agent Patterns

Vybe Agent Patterns

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

Quick Reference

MUST (BLOCKING):

• Every write command MUST include --request-id (enables idempotent retries)
• Agent MUST set VYBE_AGENT env var or --agent flag (stable identity)
• Resume MUST be called at session start before accessing focus task
• Task closure in autonomous loops MUST use vybe task set-status --status completed|blocked

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 (add to ~/.bashrc or ~/.zshrc)
export VYBE_AGENT=claude

# Verify setup
vybe status --agent claude | 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 and every write needs a request ID.

# Set agent identity once — used by all subsequent commands via env var
export VYBE_AGENT=claude

# Request ID: enables safe retries (same ID = same result)
vybe task create --request-id "plan_step1_$(date +%s)_$$" \
  --title "Implement auth" --desc "Add JWT middleware"

Note: --agent flag is the explicit alternative, but VYBE_AGENT env var is preferred — set once, no repetition.

Resume Cycle (MUST Follow)

The fundamental pattern: resume -> work -> log -> set-status -> resume.

export VYBE_AGENT=claude

# 1. Get context (advances cursor, returns focus task + memory + events)
BRIEF=$(vybe resume --request-id "resume_$(date +%s)_$$")

# 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 push --request-id "push_$(date +%s)_$$" --json \
  "{\"task_id\":\"$TASK_ID\",\"event\":{\"kind\":\"progress\",\"message\":\"Implemented JWT validation\"}}"

# 6. Close task (canonical agent path: set terminal status)
vybe task set-status --request-id "done_$(date +%s)_$$" \
  --id "$TASK_ID" --status completed

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

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 memory set --request-id "mem_$(date +%s)_$$" \
  --key api_base --value "https://staging.example.com" \
  --scope project --scope-id "$PROJECT_DIR"

# Read it back (any session, no --request-id needed for reads)
vybe memory get --key api_base --scope project --scope-id "$PROJECT_DIR"

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 memory set --key=<key> --value=<value> \
  --scope=task --scope-id=<task_id> --request-id=mem_$(date +%s)_$$

# Log significant progress + link output files in one atomic call
vybe push --request-id=push_$(date +%s)_$$ --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 --request-id "resume_$(date +%s)_$$")

  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 push --request-id "push_$(date +%s)_$$" --json \
    "{\"task_id\":\"$TASK_ID\",\"event\":{\"kind\":\"progress\",\"message\":\"Processing...\"}}"

  vybe task set-status --request-id "done_$(date +%s)_$$" \
    --id "$TASK_ID" --status completed
done

Key improvements: idempotent request IDs, success check, null checks, resume instead of brief, explicit terminal status.

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 (idempotent):

export VYBE_AGENT="${VYBE_AGENT:-planner}"
TS=$(date +%s)

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

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

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

Key improvements: timestamp-based request IDs, jq extraction, proper request ID per operation.

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 memory set --request-id "intent_$(date +%s)_$$" \
  --key current_operation --value "migrating_table_users" \
  --scope task --scope-id "$TASK_ID"

# Do the work...

# After success, clear checkpoint
vybe memory set --request-id "clear_$(date +%s)_$$" \
  --key current_operation --value "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
TS=$(date +%s)

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

vybe task create --request-id "task2_$TS" \
  --title "Extract citations" \
  --desc "Parse PDFs and extract citation graphs"

vybe task create --request-id "task3_$TS" \
  --title "Synthesize findings" \
  --desc "Aggregate results into summary report"

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

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

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

  # Execute work...

  vybe push --request-id "push_$TS" --json \
    "{\"task_id\":\"$TASK_ID\",\"artifacts\":[{\"file_path\":\"./output/papers.json\"}]}"

  vybe task set-status --request-id "done_$TS" --id "$TASK_ID" \
    --status completed
fi

Session-Spanning Code Refactor

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

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

vybe memory set --request-id "mem_$(date +%s)_$$" \
  --key files_refactored --value "checkout.go,payment.go" \
  --scope task --scope-id "$TASK_ID"

# Session crashes or context resets...

# Session 2: Resume from checkpoint
RESUME=$(vybe resume --request-id "resume_$(date +%s)_$$")
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
export VYBE_AGENT=claude

# Task lifecycle
vybe task create --request-id R --title T --desc D
vybe task begin  --request-id R --id ID
vybe task set-status --request-id R --id ID --status completed
vybe task list
vybe task get --id ID

# Push (atomic: event + memory + artifacts + status in one call)
vybe push --request-id R --json '{"task_id":"T","event":{"kind":"K","message":"M"},"artifacts":[{"file_path":"P"}]}'

# Events (read-only, no --request-id)
vybe events --task-id T

# Memory
vybe memory set  --request-id R --key K --value V --scope S --scope-id SI
vybe memory get  --key K --scope S --scope-id SI
vybe memory list --scope S --scope-id SI

# Artifacts (read-only, no --request-id)
vybe artifacts --task-id T

# Context
vybe resume --request-id R                  # advances cursor
vybe resume --peek                          # read-only, no cursor advance
vybe status                                 # agent state
vybe status --check                         # fast health gate (exit code)

Anti-Patterns

Common Errors

Converted and distributed by TomeVault — claim your Tome and manage your conversions.