agent-stream-dbg

TUI debugger for agent and multi-agent event streams (SSE, gRPC, ACP, replay).

Point it at a live backend or a recorded fixture, watch frames in a multi-pane terminal UI, and decode them through a dialect (what the bytes mean).

Transport	What it is
SSE	HTTP Server-Sent Events
gRPC	Streaming RPCs (reflection, descriptor set, or .proto)
ACP	Agent Client Protocol over stdio
Replay	JSONL fixture through the same pipeline (offline / CI)

Install

Go

go install github.com/Obedience-Corp/agent-stream-dbg/cmd/agent-stream-dbg@latest
# pin a release:
go install github.com/Obedience-Corp/agent-stream-dbg/cmd/agent-stream-dbg@v0.1.0

npm (downloads a GoReleaser archive on install; same model as Festival)

npm install -g @obedience-corp/agent-stream-dbg
npx @obedience-corp/agent-stream-dbg --help

Homebrew (Formula on the org tap — not a Cask; casks are for GUI apps)

brew tap Obedience-Corp/tap
brew trust Obedience-Corp/tap   # Homebrew 6+ once
brew install agent-stream-dbg

See homebrew/README.md and npm/README.md.

From source:

git clone https://github.com/Obedience-Corp/agent-stream-dbg.git
cd agent-stream-dbg
just install   # or: go install ./cmd/agent-stream-dbg

See also homebrew/README.md and npm/README.md.

Quick start

agent-stream-dbg

Bare launch opens the home hub:

1. Create or pick a run configuration
2. Or try an offline demo (bundled fixtures, no network)
3. Open an interactive session
4. Quit the session → return to the home hub

Key	Home hub
↑ ↓ / j k	Move
Enter	Open session (or edit if incomplete)
n	New configuration wizard
e	Edit selected config
d	Delete
q	Quit

Jump straight into interactive mode with a YAML file (demos, scripts, CI):

agent-stream-dbg --config my-config.yaml
# or
agent-stream-dbg -c demos/configs/acp-demo.yaml

Single-shot stream (no home hub):

agent-stream-dbg stream --config my-config.yaml "your message"

From a clone, CLI offline recipes without the TUI:

just demo       # multi-agent timeline (bundled fixture)
just demo-acp   # ACP explain + timeline + replay

Demos

Recordings under docs/assets/. Offline ones need no API key or live service.

Home hub

First run, multi-config select, and new-config wizard:

Flow	Recording
Empty first launch	home-ux-first-run.gif
Select → open → return home	home-ux-select-open.gif
New configuration wizard	home-ux-new-config.gif

Multi-agent TUI

Live multi-agent stream with agent lanes (fixture-backed recording):

TUI motion chrome

Energy strip, agent pulses, and flow-stage animation (demos/record-stream-anim.sh):

ACP dialect (explain, timeline, replay)

Decode Agent Client Protocol JSON-RPC sessions offline — just demo-acp / just record-acp:

ACP live multi-turn (session reuse)

Interactive TUI over stdio ACP: two prompts, same agent process and sessionId — just record-acp-live (uses cmd/demo-acp-agent, no network):

gRPC activity stream

gRPC multi-agent activity view (local daemon; not a public hosted service):

Also: tui-obey-grpc.gif, tui-obey-live.gif.

Commands

Command	Purpose
agent-stream-dbg	Home hub (default)
agent-stream-dbg -c <file>	Interactive TUI with a run config
agent-stream-dbg stream -c <file> "msg"	One message, then exit
agent-stream-dbg timeline <session.jsonl>	Parallel execution timeline
agent-stream-dbg replay <session.jsonl>	Replay a recorded session
agent-stream-dbg explain ...	Trace dialect matching per frame
agent-stream-dbg init ...	Draft a dialect from a stream or recording

Flags for stream must come before the message argument.

Trace correlation (W3C / OpenTelemetry join)

The debugger joins agent streams to backend traces when W3C context is present — it does not require a collector or OTLP exporter.

Flag / env	Effect
(default)	Observe inbound traceparent (SSE headers, gRPC trailers, payload fields) and show trace: … in the TUI when known
--otel-propagate / OTEL_PROPAGATE=true	Inject traceparent on outbound connect/send (generates a root if none exists)
--otel-traceparent / TRACEPARENT	Force a specific session parent

Session and API-call JSONL logs include trace_id / span_id when known. Offline demos and replay work unchanged when no context is present.

Interactive TUI keys

Key	Action
Type + Enter	Send (insert mode: i)
1–5	Switch panes (flow, app, timeline, events, …)
Ctrl+T	Toggle RAW (wire) vs PARSED (agent-organized)
c	Open config panel
Ctrl+S	Save config (in panel)
Ctrl+C / quit	Leave session (returns to home when launched from hub)

See USAGE.md for the full keyboard map and troubleshooting.

Configuration

A run config is YAML that picks a transport and a dialect. Create one in the home hub wizard, or copy config.yaml.example.

Configs are loaded from:

• The path you pass with -c / --config
• Well-known names in the working directory (agent-stream-dbg.yaml, config.yaml, …)
• configs/*.yaml in the working directory
• ~/.config/agent-stream-dbg/*.yaml (user library used by the home hub)

Transports

Type	Role
sse	HTTP Server-Sent Events
grpc	Streaming RPCs
acp	ACP agent process over stdio (multi-turn reuses the process)
replay	JSONL fixture path in base_url (offline / demos)

Example (SSE + OpenAI-style dialect):

transport:
  type: sse
  base_url: "http://localhost:5003"
  stream_endpoint:
    url: "/api/stream"
    method: "POST"
    auth:
      type: bearer
      token_env: API_KEY

dialect:
  file: openai

logging:
  dir: "./logs"

Auth is opt-in: omit auth: to send no credential. Full field set: config.yaml.example.

Dialects

Dialects are YAML data embedded in the binary — they define how frames map to agents, tools, and content.

Dialect	Wire	Offline without a live backend
openai	Chat Completions SSE	testdata/fixtures/openai-chat.jsonl
anthropic	Messages SSE	testdata/fixtures/anthropic-messages.jsonl
a2a	Agent2Agent	testdata/fixtures/a2a-session.jsonl
acp	Agent Client Protocol JSON-RPC	Home offline demos; just demo-acp; live: configs/acp-stdio.yaml
brainyard	Private multi-agent SSE	Fixture / home offline demo — backend is not public
obey / obey-activity	Private Obey gRPC daemon	Needs a local obey serve socket

Private backends (Brainyard, Obey) are not published with this repo; their dialects ship so you can decode recorded streams and so CI can golden-test them. Public use starts from openai / anthropic / a2a / acp, or agent-stream-dbg init against your own recording.

Example configs

Path	Notes
config.yaml.example	Full field reference
demos/configs/acp-demo.yaml	Offline ACP fixture SSE demo
configs/acp-stdio.yaml	Live ACP agent over stdio
configs/brainyard-v3.yaml	Shape sample for a private multi-agent SSE API
configs/obey-grpc.yaml	Shape sample for a local Obey daemon
configs/obey-activity-grpc.yaml	Shape sample for Obey activity streams

Logging

Sessions write under logs/ by event type, agent, session, and API call. Analyze with timeline / replay, or inspect the JSONL directly.

Documentation

• USAGE.md — modes, keyboard controls, troubleshooting
• Quick start
• TUI vs timeline
• Contributing
• Security
• Implementation
• Testing

Development

just deps
just build
just test

just --list shows the top-level recipes. Use just test, just release, and just vhs to list the recipes in those focused modules.

Release (same pipeline as Festival): tag push → GoReleaser (binaries, checksums, Homebrew Formula on homebrew-tap) → npm publish.

just release create v0.1.1   # validates, tags, pushes; CI does the rest
# or: just release tag v0.1.1

Local GoReleaser dry-run: just release snapshot (requires goreleaser on PATH).

Live TUI recording recipes are under just vhs.

VHS recordings:

just record-home-ux               # docs/assets/home-ux-*.gif
just record-acp                   # docs/assets/tui-acp-demo.gif
just record-acp-live              # docs/assets/tui-acp-live.gif
bash demos/record-stream-anim.sh  # docs/assets/tui-stream-anim.gif
# Live gRPC/SSE tapes: demos/record-obey-*.sh, .justfiles/vhs.just (need local services)

Contributing

See CONTRIBUTING.md. Short version:

1. Fork and branch
2. Add tests for new behavior
3. Run just test (or go test ./...)
4. Open a pull request

Security issues: SECURITY.md (please report privately).

License

Apache License 2.0 — see LICENSE.