Shepherd CLI¶
Debug your AI agents like you debug your code
What is Shepherd?¶
Shepherd is a command-line tool for inspecting and debugging AI agent sessions. Think of it as gdb for AI agents.
📋 Session Tracking
List, filter, and inspect all your agent sessions from the terminal.
🌳 Trace Trees
Visualize execution flows with hierarchical trace trees.
📄 JSON Export
Export traces for analysis or integration with other tools.
🔌 Multi-Provider
Works with multiple observability platforms: AIOBS and Langfuse.
💻 Interactive Shell
A REPL for exploring sessions with tab completion and history.
Quick Preview¶
$ pip install shepherd-cli
$ shepherd config init
$ shepherd sessions list
Sessions
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┓
┃ ID ┃ Name ┃ Started ┃ Duration ┃ Events ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━┩
│ be393d0d... │ pipeline-ex… │ 2025-12-03 │ 9.6s │ 4 │
│ 6dfe36bb... │ pipeline-ex… │ 2025-12-03 │ 9.8s │ 4 │
└─────────────┴──────────────┴──────────────┴──────────┴────────┘
Coming Soon¶
🤖 Shepherd Agent
AI-powered debugging with natural language queries and GDB-like features.
🔄 Deterministic Replay
Replay agent runs with exact inputs and random seeds.
🔴 Breakpoints
Set breakpoints on tool calls, LLM invocations, or conditions.
🧠 Trace Agent
AI that analyzes your execution traces.