Skip to main content

ludus run — Agent Interaction

2026-02-23T18:25:55Z by Showboat 0.6.1

1. ludus run agent ping​

1.1 Ping the default agent (main)​

ludus run agent ping

Pinging main agent...
    <- "Reply with exactly: PONG"
    -> "PONG"
  ✓ Agent is alive

Next:
  ludus run agent task MSG       Send a real task
  ludus info replay main         View session
ludus --json run agent ping
{
  "agent": "main",
  "alive": true,
  "reply": "PONG",
  "next": [
    {
      "command": "ludus run agent task MSG",
      "description": "Send a real task"
    },
    {
      "command": "ludus info replay main",
      "description": "View session"
    }
  ]
}

1.2 Ping a specific agent​

ludus --json run agent ping b4-dev
{
  "agent": "b4-dev",
  "alive": true,
  "reply": "PONG",
  "next": [
    {
      "command": "ludus run agent task MSG",
      "description": "Send a real task"
    },
    {
      "command": "ludus info replay b4-dev",
      "description": "View session"
    }
  ]
}

1.3 Ping a nonexistent agent​

ludus --json run agent ping nonexistent-agent 2>&1 || true
{
  "agent": "nonexistent-agent",
  "alive": false,
  "error": "agent ask failed (rc=1): "
}

2. ludus run agent task​

ludus --json run agent task "What agents are available? Reply with a short list."
{
  "message": "What agents are available? Reply with a short list.",
  "reply": "Two agents:\n\n- **b4-eng-mgr** \u2014 Engineering Manager. Triages, plans, delegates.\n- **b4-dev** \u2014 Developer. Implements and closes tasks. Routed via eng-mgr.",
  "next": [
    {
      "command": "ludus info intercom",
      "description": "Check intercom on Mimas"
    },
    {
      "command": "ludus info observe",
      "description": "Watch pipeline"
    }
  ]
}

3. ludus run agent ask​

ludus --json run agent ask b4-dev "Reply with exactly: HELLO"
{
  "agent": "b4-dev",
  "message": "Reply with exactly: HELLO",
  "reply": "HELLO"
}

Custom session ID​

ludus --json run agent ask main "What is 2+2?" --session-id test-session-001
{
  "agent": "main",
  "message": "What is 2+2?",
  "reply": "4."
}

4. ludus run e2e​

ludus run e2e "Create a bead titled 'E2E test' with label dev and close it immediately."

B4Arena E2E Test

Step 1/3: Reset beads (skipped — use --reset)

Step 2/3: Send task to main agent
    <- "Create a bead titled 'E2E test' with label dev and close it 
immediately."
    -> "Done — **`intercom-3tc`** created with label `dev`, closed immediately, 
pushed.

Quick note: normally I route to `eng-mgr` first (to avoid bypassing triage), but
you explicitly asked for `dev` so I went with it. 🏁"

Step 3/3: Observe pipeline
[2026-02-23T18:27:05Z] [OBSERVER] --- snapshot ---
[2026-02-23T18:27:07Z] [BEADS] Snapshot: 1 bead(s)
[2026-02-23T18:27:07Z] [BEADS] [in_progress] beads-5ip — Add test documentation to the test-calculator README (labels: eng-mgr)
[2026-02-23T18:27:09Z] [SESSIONS] Snapshot: 1 session(s), 1 active (<5min)
[2026-02-23T18:27:09Z] [SESSIONS] [agent:main:main] tokens=52838 age=3s model=claude-sonnet-4-6
[2026-02-23T18:27:11Z] [WATCHER] (no ready beads)
[2026-02-23T18:27:11Z] [OBSERVER] --- end ---

4.1 With reset​

ludus run e2e --reset "Create a bead titled 'E2E test' with label dev and close it immediately."

B4Arena E2E Test

Step 1/3: Reset beads
  ✓ Local beads DB reset: beads/.beads
  ✓ Remote beads DB reset

Step 2/3: Send task to main agent
    <- "Create a bead titled 'E2E test' with label dev and close it 
immediately."
    -> "Done — **`intercom-s4w`** created (`dev`), closed, pushed. 🏁"

Step 3/3: Observe pipeline
[2026-02-23T18:27:36Z] [OBSERVER] --- snapshot ---
[2026-02-23T18:27:38Z] [BEADS] Snapshot: 0 bead(s)
[2026-02-23T18:27:40Z] [SESSIONS] Snapshot: 1 session(s), 1 active (<5min)
[2026-02-23T18:27:40Z] [SESSIONS] [agent:main:main] tokens=53932 age=4s model=claude-sonnet-4-6
[2026-02-23T18:27:42Z] [WATCHER] (no ready beads)
[2026-02-23T18:27:42Z] [OBSERVER] --- end ---

5. ludus run watcher​

5.1 Dry-run (human output)​

ludus run watcher --dry-run

Beads Watcher
  No ready beads.

5.2 Dry-run (JSON output)​

ludus --json run watcher --dry-run
{
  "wake_lines": [],
  "notifications": []
}

5.3 Dry-run with label filter​

ludus --json run watcher --dry-run --label dev
{
  "wake_lines": [],
  "notifications": []
}

5.4 Watcher help​

ludus run watcher --help
                                                                                
 Usage: ludus run watcher [OPTIONS]                                             
                                                                                
 Poll beads and wake agents — replaces beads-watcher.sh + beads-notify.sh.      
                                                                                
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run                 Plan wakes without executing.                      │
│ --label          TEXT     Only process this compound label.                  │
│ --local                   Run bd/openclaw locally (for cron on Mimas).       │
│ --timeout        INTEGER  Agent timeout in seconds. [default: 300]           │
│ --help                    Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯

Edge Cases​

Timeout handling​

ludus --json run agent ping main --timeout 5 2>&1 || true
Usage: ludus run agent ping [OPTIONS] [AGENT]
Try 'ludus run agent ping --help' for help.
╭─ Error ──────────────────────────────────────────────────────────────────────╮
│ No such option: --timeout                                                    │
╰──────────────────────────────────────────────────────────────────────────────╯

Agent not registered​

ludus --json run agent ping ghost-agent 2>&1 || true
{
  "agent": "ghost-agent",
  "alive": false,
  "error": "agent ask failed (rc=1): "
}