# Debugging Livekit Agents

Drives a live multi-turn conversation with a LiveKit agent running locally, using `lk...

- Repository: https://github.com/fcakyon/claude-codex-settings (1195 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add fcakyon/claude-codex-settings --skill debugging-livekit-agents -g -a claude-code -y`
Codex: `npx skills add fcakyon/claude-codex-settings --skill debugging-livekit-agents -g -a codex -y`
Cursor: `npx skills add fcakyon/claude-codex-settings --skill debugging-livekit-agents -g -a cursor -y`
Gemini CLI: `npx skills add fcakyon/claude-codex-settings --skill debugging-livekit-agents -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add fcakyon/claude-codex-settings`

## Description

Drives a live multi-turn conversation with a LiveKit agent running locally, using `lk agent debugger`. Use when the user says "test my agent", "try my agent", "does this work", or "why did it call that tool", after editing an agent to check how it behaves, or when an agent on a speech-to-speech model or one that mishears users needs checking. The default for a bare "test"; for regression tests use testing-livekit-agents, for graded runs running-livekit-simulations.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Debugging a LiveKit agent live

`lk agent debugger` runs the user's agent locally as a background process and lets you drive a
conversation one turn at a time. It's built for coding agents: you play the user, choose each next
line based on the last reply, and inspect what the agent did in between.

By default the session is text: speech is off and nothing goes to a LiveKit room, so each turn is
fast. When the bug lives in the audio path, start the session in audio mode instead (see
[Audio mode](#audio-mode)).

Before the first use, confirm the command exists and read its help:

```bash
lk agent debugger --help
```

The help is thorough and is the source of truth for subcommands and flags, so this skill doesn't
restate them. If the command is missing, the installed CLI predates it. Tell the user to update
`lk` and use `testing-livekit-agents` until then. Don't guess at an older command's shape.

## The loop

**Start** the agent, **say** user turns, **inspect** what happened, edit the code, **restart**,
repeat, and **stop** when you're done. Roughly:

```bash
lk agent debugger start
lk agent debugger say "Hi, what can you do?"
lk agent debugger say "Book me a table for two tonight"
lk agent debugger stop
```

Each `say` prints everything the agent did in response (tool calls with arguments and results,
handoffs, errors) followed by the reply. Between turns you can look at the agent's chat history, a
live event stream, the process logs, and status; `--help` lists the subcommands.

**Restart after every code edit.** A running session keeps the old code, and it's easy to lose
time debugging behavior the file no longer has.

## Debugging with it

The rest: https://github.com/fcakyon/claude-codex-settings/blob/HEAD/plugins/livekit-skills/skills/debugging-livekit-agents/SKILL.md