Skip to main content

​
Explain

cmd/crewship/cmd_explain.go is “tell me what happened in this run, in plain English.” Pure orchestration over existing primitives — no new server surface area:
  1. Look up the run via fetchRun (shared with retry).
  2. Fetch journal entries filtered by the run’s agent and a window starting 5 min before created_at.
  3. Compose a prompt that includes the formatted timeline (oldest first), capped at 200 entries.
  4. Send the prompt to the default agent (or --agent override) using the same streaming pipeline as ask.
Useful for understanding why a run failed, what tools it called, or what decisions the keeper made.

​
crewship explain <run-id>

​
Examples

explain takes agent-run IDs (msg_…, legacy r_…) from crewship history — not the run_… / prn_… IDs that crewship routine runs <slug> prints. For a routine run use crewship routine report <run-id> (summary) or crewship routine logs <run-id> (timeline). Passing a run_… ID here fails fast naming the right command (exit code 3), not a bare 404.

​
Output shape

The default prompt instructs the agent to produce 3-6 bullets that highlight errors, escalations, keeper denials, budget warnings, or unexpected control flow. Normal runs collapse to one line. The exact template is buildExplainPrompt() in cmd_explain.go.

​
Common errors

  • run <id> has no agent_id; cannot scope journal lookup — the run record is incomplete.
  • no journal entries found for agent in window starting <ts> — agent has no journal activity in the scoped window.
  • no agent set to summarize. Use --agent, set CREWSHIP_DEFAULT_AGENT, or run 'crewship config set default-agent <slug>' — no default and no override.
  • run <id> not in recent window (warning, fallback to 1 h ago) — run is older than the latest 100 entries from /api/v1/runs.

​
See also