Overview
The CLI agent debugger lets a coding agent like Claude Code, Codex, or Cursor test the agent it's building. The coding agent acts as the user: it sends a turn, reads the reply, and decides what to say next. That way, it can verify what a change does instead of making assumptions. Scripts can drive the debugger the same way.
The debugger runs your agent on your machine and holds the conversation one turn at a time. Each turn prints the agent's reply along with everything that produced it: tool calls with their arguments and results, handoffs to other agents, and errors. Between turns, you can read the agent's logs and its chat history.
By default, the conversation is text: speech is off and the debugger doesn't connect to a LiveKit room, so a turn costs only your agent's own LLM and tool calls. That makes it cost-effective enough to run after every change. To test how your agent handles speech, start the session in audio mode.
To talk to your agent yourself, by typing or speaking, use Agent Console or console mode instead.
LiveKit CLI v2.18.8 introduced the debugger. If lk agent debugger isn't available, update the CLI.
Quick start
Run the following commands from your agent's project directory. You don't need to start your agent separately: the debugger launches it for you, using the same entrypoint detection as lk agent dev and lk agent console. The agent reads its own .env file for credentials.
Launch your agent under the debugger. The agent runs in the background, and if it greets the user, the greeting prints here:
lk agent debugger startSend a user turn:
lk agent debugger say "Book me a table for two tonight"The output shows each step the agent took, then its reply:
● tool: check_availability({"party_size": 2, "date": "2026-09-23"})↳ {"times": ["19:00", "20:30"]}● AgentI have tables at 7 and 8:30 tonight. Which works for you?Keep the conversation going with more
saycommands. Each turn builds on the ones before it.Stop the debugger and your agent when you're done:
lk agent debugger stop
lk agent dbg is short for lk agent debugger.
Inspect a session
Between turns, use the following commands to see what the agent did and why:
lk agent debugger logs: Print the agent's recent log output.lk agent debugger chat-history: Print the conversation as the agent recorded it, including tool calls, handoffs, and changes to instructions and tools.lk agent debugger status: Show the active agent, its tools, and the number of turns so far.
To see the log lines from a single turn beneath the step that emitted them, add --logs to say:
lk agent debugger say --logs "Cancel my reservation"
To follow a session while something else drives it, stream its events from another shell. The stream shows every message, tool call, handoff, and agent state change as it happens:
lk agent debugger events
Restart after a code change
A running session keeps the code it started with. After editing your agent, restart it to load the change and begin a fresh conversation:
lk agent debugger restart
When the debugger turns up a bug, write a unit test for it after you fix it, so a later change can't bring it back unnoticed.
Audio mode
Text mode skips speech recognition and synthesis, so it can't reveal a name transcribed with a different spelling, digits transcribed as words, or a turn that ends before the user finishes speaking. It also can't drive a realtime model that only accepts audio.
Start the session with the --audio flag to have the debugger speak each turn instead:
lk agent debugger start --audiolk agent debugger say "My order number is 4 8 1 5."
The debugger speaks each turn with LiveKit Inference TTS into your agent's microphone input, and your agent runs its full audio pipeline, including STT, turn detection, and TTS, or its realtime model. The microphone input is a continuous realtime stream, with silence between turns, so voice activity detection and endpointing behave as they do on a call.
The user line in each turn is what your agent transcribed. When its words differ from the text you sent, the sent text appears beneath it:
● YouMy order number is four eight one five.(sent: "My order number is 4 8 1 5.")
A turn lasts until your agent has heard the speech, responded, and then stayed silent for a few seconds. If your agent hears the turn but never answers, the debugger reports the turn as silent.
Audio mode uses LiveKit Inference, billed to your LiveKit Cloud project, in addition to your agent's own model usage. The debugger resolves the project the same way as other lk commands: the --project option, LIVEKIT_* environment variables, livekit.toml, or your default project. Your agent still reads its own .env file. Text mode needs no project credentials.
The mode applies to the whole session. The restart subcommand keeps it, and the status subcommand reports it. To switch modes, stop the session and start a new one.
Audio mode requires LiveKit CLI v2.19.0 or later. If the CLI doesn't recognize the --audio flag, update the CLI.
Use it from a coding agent
To have your coding agent use the debugger on its own, do either of the following:
Install the
debugging-livekit-agentsskill from LiveKit Agent Skills . It loads when you ask your coding agent to test or try your agent, and teaches it how to use the debugger:npx skills add livekit/agent-skills --skill debugging-livekit-agentsAdd instructions to your project's
AGENTS.md. The coding agents guide has a snippet to copy.
Script a conversation
Add the --json flag to any command for machine-readable output. The say subcommand returns one JSON document per turn, with the user text, what the agent heard, the agent's reply, the duration of the turn, and a list of events. It exits with a non-zero code when the agent reports an error or the turn times out, so a script can detect failures without parsing the output.
lk agent debugger start --json > /dev/nulllk agent debugger say --json "What are your hours?" | jq -r '.reply'lk agent debugger stop
For the full event schema, see JSON output.
Run several agents at once
The debugger runs one session per port, on port 8775 by default. To run another agent alongside it, give each session its own port and pass the same port to every command for that session:
lk agent debugger start --port 8776lk agent debugger say --port 8776 "Hello"
A session stops on its own after 30 minutes without a command, so a forgotten session doesn't leave an agent process running.
Limitations
Text mode can't test speech behavior. Use audio mode for transcription and endpointing.
Even in audio mode, each turn waits for the agent to finish, so the debugger can't interrupt the agent mid-reply, and it can't assess how the agent sounds. For those, talk to the agent in Agent Console or run audio simulations.
If your agent pauses for a long time before finishing its answer, for example while a realtime model waits on a delegated response, the turn can end early. The rest of the answer then appears at the start of the next turn, labeled (before this turn).