CLI Agent Debugger

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 in text mode 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.

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 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.

1. 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 start

2. Send 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"]}
   
   ● Agent
     I have tables at 7 and 8:30 tonight. Which works for you?

3. Keep the conversation going with more say commands. Each turn builds on the ones before it.

4. 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.

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-agents skill 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-agents

• Add 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. A say turn returns one JSON document with the user text, the agent's reply, the turn's duration, and a list of events. The say subcommand 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/null
lk 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 8776
lk 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

The debugger runs in text mode, so it can't show you anything about speech. Turn-taking, interruptions, transcription accuracy, and how the agent sounds all need audio. For those, talk to the agent in Agent Console or run audio simulations.

Additional resources