VM API

Human language docs for the exe.dev agent orchestration system

Worker Loops ~/bin/worker

Autonomous shelley sessions that run until complete or hitting context limits. The worker script spawns sessions, enforces limits, and manages state.

Start a loop

worker start <name> --task "description of work" --dir /path/to/project [--max 10]

Check running loops

worker list

Shows all workers with status, session count, and working directory.

Stop a loop

worker stop <name>       # graceful stop
worker stop-all          # stop everything

View logs

worker log <name>        # show recent output
tail -f ~/.workers/<name>.log  # live tail

Deja Memory deja.coey.dev

Persistent memory that survives across sessions. Agents query deja at session start to get relevant context.

Query for relevant memories

curl -s -X POST https://deja.coey.dev/inject \
  -H "Content-Type: application/json" \
  -d '{"context": "describe your task", "format": "prompt", "limit": 5}'

Returns learnings relevant to the context. One call per session is enough.

Store a learning

curl -s -X POST https://deja.coey.dev/learn \
  -H "Authorization: Bearer $(cat ~/.deja-api-key)" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger": "when this is relevant",
    "learning": "what to remember",
    "confidence": 0.9
  }'

Memory types

Session Search ~/bin/shelley-*

52+ past shelley sessions = 157MB of searchable memory. Find what you tried before.

Search past sessions

~/bin/shelley-search "pattern" [limit]

Finds conversations mentioning the pattern, shows context snippets.

Get compact context for injection

~/bin/shelley-recall "error message" [limit]

Returns HANDOFF notes and relevant snippets, formatted for prompt injection.

Context Management ~/bin/ctx

Selective editing of the context window. Delete tool outputs you don't need anymore.

Check context size

ctx size <conversation_id>

Search for messages

ctx search <conversation_id> "search term"

Returns message IDs matching the term.

Delete messages

ctx forget <msg_id> [msg_id...]

List recent messages

ctx list <conversation_id> [limit]

Health Checks gates/health.sh

Worker loops auto-run gates/health.sh before each session. Output is injected into the prompt.

Create a health check

#!/bin/bash
# gates/health.sh - exit 0 = healthy, exit 1 = blockers

# Type check
ERRORS=$(npx tsc --noEmit 2>&1 | grep "error TS" | head -10)
if [ -n "$ERRORS" ]; then
  echo "❌ Type errors - FIX FIRST:"
  echo "$ERRORS"
  
  # Auto-recall past attempts at this error
  FIRST_ERROR=$(echo "$ERRORS" | head -1)
  ~/bin/shelley-recall "$FIRST_ERROR" 1 2>/dev/null
  
  exit 1
fi

echo "✅ Build passes"
exit 0

What to check

Pre-action Critic check.mjs

Optional sanity check before taking action. Catches red flags before they become problems.

node /home/exedev/check.mjs "what you're about to do"

Red flags it catches

Returns PROCEED (exit 0) or STOP (exit 1).

Steerer ~/bin/steerer

Meta-loop that watches a worker. Rescues orphaned work, monitors errors, updates deja.

What it does

• Commits orphans: If worker session dies with uncommitted changes, steerer commits them
• Monitors errors: Runs type check, logs error count
• Updates deja: Posts status updates for next session

# Run alongside worker (in separate terminal)
~/bin/steerer

Quick Reference

# Start a worker loop
worker start myproject --task "implement feature X" --dir /path/to/project

# Monitor it
worker list
worker log myproject

# Steer by updating memory
curl -X POST https://deja.coey.dev/learn ...

# What did we try before?
~/bin/shelley-search "websocket"
~/bin/shelley-recall "error TS2345"

# Find and delete old messages
ctx search CONV_ID "big tool output"
ctx forget MSG_ID1 MSG_ID2
ctx size CONV_ID