AGENTS.md by stephen-derosa · Pull Request #91 · livekit/client-sdk-cpp

stephen-derosa · 2026-04-09T20:22:21Z

Overview

An AGENTS.MD file for guiding cursor on development inside the project

Key points

Architecture
Build preferences
Testing
Formatting
comments on readability vs performance

Any other points?

Copilot

Pull request overview

Adds an AGENTS.md guidance document intended for development agents working in the LiveKit C++ Client SDK repo, summarizing architecture, build flow, coding conventions, dependencies, testing, and pitfalls.

Changes:

Introduces AGENTS.md with project architecture notes and key internal/public types.
Documents recommended build and packaging commands, plus dependency/tooling expectations.
Captures coding conventions (logging, public API boundaries, error handling) and testing guidance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

AGENTS.md

Copilot · 2026-04-09T20:24:52Z

AGENTS.md

+Adhere to the formatting rules if TODO: @alan
+


The Formatting section is currently a placeholder (“TODO: @alan”), which leaves agents without actionable guidance. Replace with concrete formatting instructions (e.g., clang-format invocation/config) or remove the section until it’s defined.

Suggested change

Adhere to the formatting rules if TODO: @alan

- Match the style of the surrounding code and keep formatting changes limited to the files you touch.

- Use consistent indentation, spacing, and brace style with nearby C++ headers, sources, CMake files, and Markdown.

- Keep `#include` ordering and whitespace consistent with the existing file rather than reformatting unrelated code.

- If the repository or your editor provides formatting configuration, run it before submitting changes; otherwise prefer minimal, manual formatting-only edits.

AGENTS.md

stephen-derosa · 2026-04-09T20:26:00Z

AGENTS.md

+When adding new client facing functionality, add benchmarking to understand the limiations of the new functionality.
+
+## Formatting
+Adhere to the formatting rules if TODO: @alan


@alan-george-lk i wonder what the best way t provide this is. My reading on Agents.md leads me to believe we should just put code snippets directly inline. Does clang-tidy provide a list or would it be reasonable to ask cursor:
"Write me an AGENTS.md ## Formatting section which has code examples to be followed for clang-tidy cpp formatting" (or a better prompt)

We as a team should come up with a .clang-format style we all like, then the cpp-linter action I am using in the clang-tidy PR can actually run/enforce that for us. But as far as this file, we could point the Agent to the .clang-format file once that becomes a thing. Probably a separate scope of work beyond clang-tidy, easy to implement but harder to align on preferences ;)

See here: https://clang.llvm.org/docs/ClangFormat.html

xianshijing-lk · 2026-04-13T18:35:16Z

AGENTS.md

+1. windows x64
+2. linux x86_64
+3. linux arm64
+3. macOS x86_64


there are two 3 here

I don't know if the Agent would care, but it's good MD practice generally to just do:

1. 1. 1.

and then it'll render the right order

xianshijing-lk · 2026-04-13T18:39:55Z

AGENTS.md

+SDK features follow pattern:
+
+1. Serialize a protobuf `FfiRequest` message.
+2. Send it to Rust via `FfiClient::instance().sendRequest(req)`.


there are two types of ffi messages here, one is synchronous call that we send a ffi request to rust ffi layer, and get back the FfiResponse.

Another one is async calls:
c++ setup a async handler that listens to event with a |request_async_id|
Serialize a protobuf FfiRequest message with a |request_async_id|
Send it to Rust via FfiClient::instance().sendRequest(req).
Receive a synchronous FfiResponse and an asynchronous FfiEvent callback.

xianshijing-lk · 2026-04-13T18:48:52Z

AGENTS.md

+| `cmake/` | Build helpers (`protobuf.cmake`, `spdlog.cmake`, `LiveKitConfig.cmake.in`) |
+| `docker/` | Dockerfile for CI and SDK distribution images |
+| `.github/workflows/` | GitHub Actions CI workflows |
+


I’m wondering if we should add a dedicated section to clarify the FFI design rules. For example, we should explicitly state that the main implementation logic lives in Rust, and that the C++ layer must remain a thin wrapper over the FFI.

It would also be helpful to include a section describing the threading model, covering questions like:

Is FfiClient thread-safe? (this should be clearly defined)
On which threads are RoomDelegate callbacks invoked?
Are they coming from FFI/Tokio threads?
In the FFI layer, are audio callbacks executed on a dedicated high-priority Tokio runtime?
What are the threading models for:
LocalAudioTrack / LocalVideoTrack
AudioStream / VideoStream
DataStream
What are the thread-safety guarantees of the public API?
(explicitly define whether it is thread-safe or not)

If applicable, clarifying these points would make the design much easier to understand and help avoid misuse.

xianshijing-lk · 2026-04-13T19:16:44Z

Do you find it useful to have the agents.md ?

like, if claude / codex / cursor generate better results with this agents.md ? or it does not have much impact?

alan-george-lk · 2026-04-14T17:47:32Z

AGENTS.md

+
+### Core Principle
+Rust owns as much of the business logic as possible. If a feature may be used by another SDK it should be implemented in Rust. Since this is an SDK,
+ensure backwards compatibility is maintained when possible.


Maybe explicitly list to avoid breaking changes in headers, or if absolutely necessary, prompt the user/flag them explicitly and require opt-in before proceeding?

Edit: looks like this is called out later in the file

alan-george-lk · 2026-04-14T17:48:22Z

AGENTS.md

+1. windows x64
+2. linux x86_64
+3. linux arm64
+3. macOS x86_64


I don't know if the Agent would care, but it's good MD practice generally to just do:

1. 1. 1.

and then it'll render the right order

alan-george-lk · 2026-04-14T17:49:57Z

AGENTS.md

+
+When making larger scale changes, check with the developer before committing to architecture changes involving changes to the `client-sdk-rust/` submodule.
+
+### Directory Layout


Is this a required feature of this file? I fear this will get out of date quickly.

Or maybe we add a clause saying "whenever directory structure changes, update AGENTS.md file"

alan-george-lk · 2026-04-14T17:51:17Z

AGENTS.md

+- **`LocalParticipant` / `RemoteParticipant`** — Participant objects for publishing and receiving tracks.
+
+## Build
+for building, use the build.sh script for Linux and macOS, and the build.cmd script for Windows. Do not invoke CMake directly.


Nit: fully valid markdown has new lines between section headers/content. There's a nice markdownlint VSCode plugin that I use to help with this stuff: https://marketplace.cursorapi.com/items/?itemName=DavidAnson.vscode-markdownlint

alan-george-lk · 2026-04-14T17:52:49Z

AGENTS.md

+for building, use the build.sh script for Linux and macOS, and the build.cmd script for Windows. Do not invoke CMake directly.
+
+```
+./build.sh debug              # Debug build


Similar comment to the repo directory structure, might be good to call out any adjustments to these script args should be updated in READMEs and this agents file

alan-george-lk · 2026-04-14T17:54:17Z

AGENTS.md

+- `LK_LOG_INFO` — initialization, critical state changes.
+- `LK_LOG_DEBUG` — potentially useful diagnostic info.
+- Do not spam logs. Keep it concise.
+- In production/internal SDK code, do not use `std::cout`, `std::cerr`, `printf`, or raw spdlog calls; use the logging APIs instead. Tests may use standard streams sparingly for ad hoc diagnostics when appropriate.


Good call out -- in my experience I also like using logging APIs for unit tests, that way you can add more detail at a debug/trace level and keep that off for production/CI runs.

alan-george-lk · 2026-04-14T17:56:10Z

AGENTS.md

+
+### Error Handling
+
+- Throw exceptions for broken/unrecoverable states.


This is probably a larger team discussion: I am fairly anti-exception for robotics/embedded applications. Some safety certification specifications explicitly disallow exceptions. This would apply more to AV/aerospace customers of LiveKit due to safety requirements.

It would be unfortunate to lose a customer opportunity due to C++ feature usage like this. Looking at the existing SDK code we may not be able to undo existing exceptions, but for new code I'd prefer not to use them when possible.

bool, std::optional, Expected<Type, Error> (in STL later), etc. (which I think we're already using in places)

stephen-derosa requested review from alan-george-lk, Copilot and xianshijing-lk April 9, 2026 20:22

stephen-derosa self-assigned this Apr 9, 2026

Copilot started reviewing on behalf of stephen-derosa April 9, 2026 20:22 View session

Copilot AI reviewed Apr 9, 2026

View reviewed changes

stephen-derosa commented Apr 9, 2026

View reviewed changes

stephen-derosa force-pushed the sderosa/clt-2485-AGENTS.MD branch 2 times, most recently from bc80b84 to cf6bc19 Compare April 13, 2026 18:00

AGENTS.md

348ce39

stephen-derosa force-pushed the sderosa/clt-2485-AGENTS.MD branch from cf6bc19 to 348ce39 Compare April 13, 2026 18:04

xianshijing-lk reviewed Apr 13, 2026

View reviewed changes

alan-george-lk reviewed Apr 14, 2026

View reviewed changes

-Adhere to the formatting rules if TODO: @alan
+- Match the style of the surrounding code and keep formatting changes limited to the files you touch.
+- Use consistent indentation, spacing, and brace style with nearby C++ headers, sources, CMake files, and Markdown.
+- Keep `#include` ordering and whitespace consistent with the existing file rather than reformatting unrelated code.
+- If the repository or your editor provides formatting configuration, run it before submitting changes; otherwise prefer minimal, manual formatting-only edits.


		When making larger scale changes, check with the developer before committing to architecture changes involving changes to the `client-sdk-rust/` submodule.

		### Directory Layout


		### Error Handling

		- Throw exceptions for broken/unrecoverable states.

Conversation

stephen-derosa commented Apr 9, 2026

Overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xianshijing-lk commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alan-george-lk Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

xianshijing-lk commented Apr 13, 2026 •

edited

Loading

alan-george-lk Apr 14, 2026 •

edited

Loading