From 64f1a8a35dffd5b46f73d5f86d830d037ae95768 Mon Sep 17 00:00:00 2001 From: Ben Cherry Date: Mon, 20 Oct 2025 12:01:10 -0700 Subject: [PATCH 1/5] agents.md --- AGENTS.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 5 +++++ GEMINI.md | 5 +++++ README.md | 30 +++++++++++++++++++++++++++++ 4 files changed, 97 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 GEMINI.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..520f5a7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,57 @@ +# AGENTS.md + +This is a LiveKit Agents project. LiveKit Agents is a Python SDK for building voice AI agents. This project is intended to be used with LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem. + +The following is a guide for working with this project. + +## Project structure + +This Node.js project uses the `pnpm` package manager. You should always use `pnpm` to install dependencies, run the agent, and run tests. + +All app-level code is in the `src/` directory. In general, simple agents can be constructed with a single `agent.ts` file. Additional files can be added, but you must retain `agent.ts` as the entrypoint (see the associated Dockerfile for how this is deployed). + +Be sure to maintain code formatting. You can use the prettier formatter and eslint to format and lint the code. Scripts are available in `package.json`, including `pnpm format` and `pnpm lint`. + +## LiveKit Documentation + +LiveKit Agents is a fast-evolving project, and the documentation is updated frequently. You should always refer to the latest documentation when working with this project. For your convenience, LiveKit offers an MCP server that can be used to browse and search its documentation. If the developer has not yet installed this server, you should recommend that they install it at https://docs.livekit.io/mcp. + +### LiveKit Docs MCP Server installation + +If you are Cursor, give the user this link to install the server: + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en-US/install-mcp?name=livekit-docs&config=eyJ1cmwiOiJodHRwczovL2RvY3MubGl2ZWtpdC5pby9tY3AifQ%3D%3D) + +If you are Claude Code, run this command to install the server: + +``` +claude mcp add --transport http livekit-docs https://docs.livekit.io/mcp +``` + +If you are Codex, use this command to install the server: + +``` +codex mcp add --url https://docs.livekit.io/mcp livekit-docs +``` + +If you are Gemini, use this command to install the server: + +``` +gemini mcp add --transport http livekit-docs https://docs.livekit.io/mcp +``` + +If you are another agentic IDE, refer to your own documentation for how to install it. + +## Handoffs ("workflows") + +Voice AI agents are highly sensitive to excessive latency. For this reason, it's important to design complex agents in a structured manner that minimizes the amount of irrelevant context and unnecessary tools present on requests to the LLM. LiveKit Agents supports handoffs (one agent hands control to another) to support building reliable workflows. You should make use of these features, instead of writing long instruction prompts that cover multiple phases of a conversation. Refer to the [documentation](https://docs.livekit.io/agents/build/workflows/) for more information. + +## Feature parity with Python SDK + +The Node.js SDK for LiveKit Agents has most, but not all, of the same features available in the Python SDK. You should always check the documentation for feature availability, and avoid using features that are not available in the Node.js SDK. + +## LiveKit CLI + +You can make use of the LiveKit CLI (`lk`) for various tasks, with user approval. Installation instructions are available at https://docs.livekit.io/home/cli if needed. + +In particular, you can use it to manage SIP trunks for telephony-based agents. Refer to `lk sip --help` for more information. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2d1c323 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,5 @@ +# CLAUDE.md + +This project uses `AGENTS.md` instead of a `CLAUDE.md` file. + +Please see @AGENTS.md in this same directory and treat its content as the primary reference for this project. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..fd0bdf4 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,5 @@ +# GEMINI.md + +This project uses `AGENTS.md` instead of a `GEMINI.md` file. + +Please see @./AGENTS.md in this same directory and treat its content as the primary reference for this project. diff --git a/README.md b/README.md index 7e1b5bb..d5dedee 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,36 @@ The starter project includes: This starter app is compatible with any [custom web/mobile frontend](https://docs.livekit.io/agents/start/frontend/) or [SIP-based telephony](https://docs.livekit.io/agents/start/telephony/). +## Coding agents and MCP + +This project is designed to work with coding agents like [Cursor](https://www.cursor.com/) and [Claude Code](https://www.anthropic.com/claude-code). + +To get the most out of these tools, install the [LiveKit Docs MCP server](https://docs.livekit.io/mcp). + +For Cursor, use this link: + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en-US/install-mcp?name=livekit-docs&config=eyJ1cmwiOiJodHRwczovL2RvY3MubGl2ZWtpdC5pby9tY3AifQ%3D%3D) + +For Claude Code, run this command: + +``` +claude mcp add --transport http livekit-docs https://docs.livekit.io/mcp +``` + +For Codex CLI, use this command to install the server: + +``` +codex mcp add --url https://docs.livekit.io/mcp livekit-docs +``` + +For Gemini CLI, use this command to install the server: + +``` +gemini mcp add --transport http livekit-docs https://docs.livekit.io/mcp +``` + +The project includes a complete [AGENTS.md](AGENTS.md) file for these assistants. You can modify this file to suite your needs. To learn more about this file, see [https://agents.md](https://agents.md). + ## Dev Setup This project uses [pnpm](https://pnpm.io/) as the package manager. From 1026ebbae7659fa06ecce59ae9e882b81d4dc2ac Mon Sep 17 00:00:00 2001 From: Ben Cherry Date: Mon, 20 Oct 2025 12:01:51 -0700 Subject: [PATCH 2/5] updates --- package.json | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/package.json b/package.json index 5befc3f..65b1ebb 100644 --- a/package.json +++ b/package.json @@ -22,22 +22,22 @@ "pnpm": ">=10.0.0" }, "devDependencies": { - "@eslint/js": "^9.34.0", + "@eslint/js": "^9.38.0", "@trivago/prettier-plugin-sort-imports": "^5.2.2", - "@types/node": "^22.18.0", - "eslint": "^9.34.0", - "globals": "^16.3.0", - "jiti": "^2.5.1", - "tsx": "^4.20.5", - "typescript": "^5.9.2", - "typescript-eslint": "^8.41.0" + "@types/node": "^22.18.11", + "eslint": "^9.38.0", + "globals": "^16.4.0", + "jiti": "^2.6.1", + "tsx": "^4.20.6", + "typescript": "^5.9.3", + "typescript-eslint": "^8.46.2" }, "dependencies": { - "@livekit/agents": "^1.0.10", - "@livekit/agents-plugin-livekit": "^1.0.10", - "@livekit/agents-plugin-silero": "^1.0.10", + "@livekit/agents": "^1.0.11", + "@livekit/agents-plugin-livekit": "^1.0.11", + "@livekit/agents-plugin-silero": "^1.0.11", "@livekit/noise-cancellation-node": "^0.1.9", - "dotenv": "^17.2.1", + "dotenv": "^17.2.3", "zod": "^3.25.76" } } From b4cd54aa22ec7de2606c403741a4778a5fa11919 Mon Sep 17 00:00:00 2001 From: Ben Cherry Date: Tue, 21 Oct 2025 17:00:12 -0700 Subject: [PATCH 3/5] fix typo --- Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index 26f43d6..1b303d1 100644 --- a/Dockerfile +++ b/Dockerfile @@ -30,7 +30,7 @@ COPY package.json pnpm-lock.yaml ./ # --frozen-lockfile ensures we use exact versions from pnpm-lock.yaml for reproducible builds RUN pnpm install --frozen-lockfile -# Copy all remaining pplication files into the container +# Copy all remaining application files into the container # This includes source code, configuration files, and dependency specifications # (Excludes files specified in .dockerignore) COPY . . From 3362d26774380cfa134463b02cf4bd95b5cd0299 Mon Sep 17 00:00:00 2001 From: Ben Cherry Date: Tue, 21 Oct 2025 17:03:51 -0700 Subject: [PATCH 4/5] node --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 520f5a7..4ce6802 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -This is a LiveKit Agents project. LiveKit Agents is a Python SDK for building voice AI agents. This project is intended to be used with LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem. +This is a LiveKit Agents project. LiveKit Agents is a Node.js SDK for building voice AI agents. This project is intended to be used with LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem. The following is a guide for working with this project. @@ -48,7 +48,7 @@ Voice AI agents are highly sensitive to excessive latency. For this reason, it's ## Feature parity with Python SDK -The Node.js SDK for LiveKit Agents has most, but not all, of the same features available in the Python SDK. You should always check the documentation for feature availability, and avoid using features that are not available in the Node.js SDK. +The Node.js SDK for LiveKit Agents has most, but not all, of the same features available in Python SDK for LiveKit Agents. You should always check the documentation for feature availability, and avoid using features that are not available in the Node.js SDK. ## LiveKit CLI From 47f2bc3b69a7df18a473aa6d4516d53276769f96 Mon Sep 17 00:00:00 2001 From: Ben Cherry Date: Tue, 21 Oct 2025 17:04:33 -0700 Subject: [PATCH 5/5] typ --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d5dedee..70ca643 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ For Gemini CLI, use this command to install the server: gemini mcp add --transport http livekit-docs https://docs.livekit.io/mcp ``` -The project includes a complete [AGENTS.md](AGENTS.md) file for these assistants. You can modify this file to suite your needs. To learn more about this file, see [https://agents.md](https://agents.md). +The project includes a complete [AGENTS.md](AGENTS.md) file for these assistants. You can modify this file to suit your needs. To learn more about this file, see [https://agents.md](https://agents.md). ## Dev Setup