# Running Livekit Simulations

Runs LiveKit agent simulations and acts on the results.

- 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 running-livekit-simulations -g -a claude-code -y`
Codex: `npx skills add fcakyon/claude-codex-settings --skill running-livekit-simulations -g -a codex -y`
Cursor: `npx skills add fcakyon/claude-codex-settings --skill running-livekit-simulations -g -a cursor -y`
Gemini CLI: `npx skills add fcakyon/claude-codex-settings --skill running-livekit-simulations -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add fcakyon/claude-codex-settings`

## Description

Runs LiveKit agent simulations and acts on the results. Use when the user says "run my simulations", "regression test my agent before deploying", "run the scenarios", "use lk agent simulate", "did my agent pass", "why did this scenario fail", "run simulations in CI", "test the audio pipeline", "check turn-taking and interruptions", or wants to check whole-conversation behavior before shipping. Covers text and audio mode and what each catches, running against a local or deployed agent, degraded-audio flags, automating a pre-release run, and triaging failures with list, view and export. For writing the scenarios use writing-livekit-scenarios. Not the default for a bare "test my agent", which goes to debugging-livekit-agents. Use this skill when the user names simulations, scenarios, a run, CI, or shipping.

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

# Running LiveKit simulations

A simulation plays a scenario against the real agent using an LLM-driven simulated user, then a
judge grades the transcript. A unit test asserts on one turn. A simulation tells you whether a
*whole conversation* reached the right outcome.

Read `lk agent simulate --help` before running. Subcommands and flags change, a wrong flag wastes a
paid run, and this skill doesn't restate them. `reading-livekit-docs` has the rest.

## When to reach for a simulation

Use simulations to regression-test long-horizon behavior before deploying to production: whether a
multi-turn conversation reaches the right outcome when the caller backtracks, whether details
gathered early survive to the end, whether the agent holds to its instructions under pressure, and
whether it ended in the right *state*. For a single turn, use `testing-livekit-agents`; to poke at
behavior while editing, use `debugging-livekit-agents`.

## Running

Run from the agent's project directory. The mode is a subcommand:

```bash
lk agent simulate text --scenarios scenarios.yaml    # see --help for the current flags
```

With no scenario file, the CLI generates scenarios from the agent's source. That **uploads the
code**, and the CLI asks for confirmation first. Generation belongs to `writing-livekit-scenarios`.

By default the CLI starts the agent as a local worker, dispatches the scenarios to it, and stops it
when the run ends. An option lets you grade an already-running agent by name instead. That needs a
scenario file, since there's no local source to generate from.

Concurrency is limited per run and per project. The docs have the current limits.

## Text or audio

**Text is the default**, and it's the right one. The simulated user exchanges text with the agent,
so the run exercises the LLM, the tools and the conversation logic while the framework turns off
STT, TTS and VAD. It's faster, cheaper and more deterministic. Use it for iteration and for anything
automated.

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