Use cpp-tools

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
       builds: ${{ steps.filter.outputs.builds }}
       tests:  ${{ steps.filter.outputs.tests }}
       docs:   ${{ steps.filter.outputs.docs }}
-      cpp_checks: ${{ steps.filter.outputs.cpp_checks }}
+      cpp_tools: ${{ steps.filter.outputs.cpp_tools }}
       rust_release_check: ${{ steps.filter.outputs.rust_release_check }}
       docker: ${{ steps.filter.outputs.docker }}
     steps:
@@ -40,6 +40,7 @@ jobs:
               - benchmarks/**
               - cpp-example-collection
               - cpp-example-collection/**
+              - client-sdk-rust
               - client-sdk-rust/**
               - cmake/**
               - CMakeLists.txt
@@ -52,6 +53,7 @@ jobs:
             tests:
               - src/**
               - include/**
+              - client-sdk-rust
               - client-sdk-rust/**
               - cmake/**
               - .token_helpers/**
@@ -70,20 +72,22 @@ jobs:
               - .github/workflows/ci.yml
               - .github/workflows/generate-docs.yml
               - .github/workflows/publish-docs.yml
-            cpp_checks:
+            cpp_tools:
               - src/**
               - include/**
               - benchmarks/**
+              - client-sdk-rust
               - client-sdk-rust/**
               - cmake/**
               - CMakeLists.txt
               - CMakePresets.json
               - scripts/clang-format.sh
               - scripts/clang-tidy.sh
-              - .clang-format
-              - .clang-tidy
+              - cpp-tools
+              - cpp-tools/**
+              - .gitmodules
               - .github/workflows/ci.yml
-              - .github/workflows/cpp-checks.yml
+              - .github/workflows/cpp-tools.yml
             docker:
               - docker/**
               - .github/workflows/ci.yml
@@ -129,11 +133,11 @@ jobs:
     name: Link Check
     uses: ./.github/workflows/link_check.yml
 
-  cpp-checks:
-    name: C++ Checks
+  cpp-tools:
+    name: C++ Tools
     needs: changes
-    if: ${{ needs.changes.outputs.cpp_checks == 'true' || github.event_name == 'workflow_dispatch' }}
-    uses: ./.github/workflows/cpp-checks.yml
+    if: ${{ needs.changes.outputs.cpp_tools == 'true' || github.event_name == 'workflow_dispatch' }}
+    uses: ./.github/workflows/cpp-tools.yml
 
   generate-docs:
     name: Generate Docs
@@ -162,7 +166,7 @@ jobs:
       - docker-images
       - tests
       - license-check
-      - cpp-checks
+      - cpp-tools
       - generate-docs
       - link-check
       - rust-release-check

.github/workflows/cpp-checks.yml → .github/workflows/cpp-tools.yml

@@ -1,4 +1,4 @@
-name: C++ Checks
+name: C++ Tools
 
 # Called by top-level ci.yml
 on:
@@ -13,14 +13,21 @@ jobs:
     name: clang-format
     runs-on: ubuntu-latest
     continue-on-error: false
+    timeout-minutes: 15
 
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
-          # No submodules: scripts/clang-format.sh only walks our own src/ tree
+          # Initialize only cpp-tools below; formatting still scans project C++ paths.
           fetch-depth: 1
 
+      - name: Initialize cpp-tools
+        run: git submodule update --init cpp-tools
+
+      - name: Install shared clang-format configuration
+        run: ./cpp-tools/install.sh clang-format --repo-root "$GITHUB_WORKSPACE"
+
       - name: Install clang-format 22
         run: |
           set -eux
@@ -47,6 +54,7 @@ jobs:
     name: clang-tidy
     runs-on: ubuntu-latest
     continue-on-error: false
+    timeout-minutes: 45
 
     steps:
       - name: Checkout (with submodules)
@@ -55,6 +63,9 @@ jobs:
           submodules: recursive
           fetch-depth: 1
 
+      - name: Install shared clang-tidy configuration
+        run: ./cpp-tools/install.sh clang-tidy --repo-root "$GITHUB_WORKSPACE"
+
       - name: Install dependencies
         run: |
           set -eux
@@ -82,7 +93,7 @@ jobs:
           sudo ln -sf /usr/bin/clang-tidy-19 /usr/local/bin/clang-tidy
           sudo ln -sf /usr/bin/run-clang-tidy-19 /usr/local/bin/run-clang-tidy
           clang-tidy --version
-          run-clang-tidy --help | head -1 || true
+          run-clang-tidy --help >/dev/null
 
       - name: Install Rust (stable)
         uses: dtolnay/rust-toolchain@fa04a1451ff1842e2626ccb99004d0195b455a88
@@ -96,7 +107,7 @@ jobs:
           LLVM_VERSION=$(llvm-config --version | cut -d. -f1)
           echo "LIBCLANG_PATH=/usr/lib/llvm-${LLVM_VERSION}/lib" >> "$GITHUB_ENV"
 
-      - name: CMake configure
+      - name: Configure compilation database
         run: cmake --preset linux-release
 
       - name: Generate protobuf headers

.gitignore

@@ -23,6 +23,9 @@ docs/doxygen/latex/
 .vs/
 .vscode/
 .cursor/
+# Installed by cpp-tools/install.sh
+.clang-format
+.clang-tidy
 # Compiled output
 bin/
 lib/

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "cpp-example-collection"]
 	path = cpp-example-collection
 	url = https://github.com/livekit-examples/cpp-example-collection.git
+[submodule "cpp-tools"]
+	path = cpp-tools
+	url = https://github.com/livekit/cpp-tools.git

AGENTS.md

@@ -1,5 +1,17 @@
 # AGENTS.md — LiveKit C++ Client SDK
 
+## Shared C++ Baseline
+
+Follow `cpp-tools/AGENTS.md` for shared C++ rules and this file for SDK-specific
+guidance.
+
+Before C++ work, verify the shared guidance and root `.clang-format` /
+`.clang-tidy` symlinks are present. If not, flag it and recommend
+`git submodule update --init cpp-tools` or `./cpp-tools/install.sh` as
+appropriate. Never use `--force` without approval or claim tooling verification
+while these prerequisites are missing. Project-specific commands are documented
+in `docs/tools.md`.
+
 ## Project Overview
 
 This is **client-sdk-cpp**, the official LiveKit C++ client SDK. It wraps a Rust core (`client-sdk-rust/`) via a protobuf-based FFI bridge. All WebRTC, networking, and media logic lives in Rust; the C++ layer provides an ergonomic API for C++ consumers.
@@ -76,10 +88,11 @@ Be sure to update the directory layout in this file if the directory layout chan
 | `src/tests/` | Google Test integration and stress tests |
 | `examples/` | In-tree example applications |
 | `client-sdk-rust/` | Git submodule holding the Rust core of the SDK|
+| `cpp-tools/` | Git submodule holding shared LiveKit C++ engineering guidance, clang-format / clang-tidy configs, scripts, docs, and CI workflow |
 | `client-sdk-rust/livekit-ffi/protocol/*.proto` | FFI contract (protobuf definitions, read-only reference) |
 | `cmake/` | Build helpers (`protobuf.cmake`, `spdlog.cmake`, `nlohmann_json.cmake`, `LiveKitConfig.cmake.in`) |
 | `docker/` | Dockerfile for CI and SDK distribution images |
-| `scripts/` | Developer / CI helper scripts (e.g. `clang-tidy.sh`) |
+| `scripts/` | Local helper scripts for SDK-specific development tasks |
 | `docs/` | Documentation root. `docs/` holds hand-written long-form Markdown intended to also read well on GitHub. |
 | `docs/doxygen/` | Doxygen tool config, theme assets, and Doxygen-only content (`Doxyfile`, `index.md` mainpage, `customization/*.css`, `customization/header.html`, `customization/favicon.ico`). Files here use Doxygen-only syntax (`@ref`, `@brief`, …) and are not intended for human reading on their own. |
 | `.github/workflows/` | GitHub Actions CI workflows |
@@ -305,33 +318,12 @@ internal symbols are too noisy to enforce) and `WARN_AS_ERROR = FAIL_ON_WARNINGS
 so any other warning (broken `@ref`, unknown `@command`, unsupported HTML tag,
 malformed table, missing `@param` on a documented function, …) fails the build.
 
-### Integer Types
-
-- Prefer fixed-width integer types from `<cstdint>` (`std::int32_t`, `std::uint64_t`, etc.) over raw primitive integer types when size or signedness matters.
-- This applies in public APIs, FFI/protobuf-facing code, serialized payloads, handles, timestamps, IDs, and any cross-platform boundary where integer width must be explicit.
-- Use raw primitive integer types only when the value is intentionally platform-sized or when preserving an existing public API is necessary for backwards compatibility.
-- Do not change an existing public API from a raw primitive integer type to a fixed-width type for style consistency alone unless the compatibility impact has been reviewed.
-
-### Git Practices
-
-- Use `git mv` when moving or renaming files.
-
 ### CMake
 
 - spdlog is linked **PRIVATE** to the `livekit` target. It must not appear in exported/installed dependencies.
 - protobuf is vendored via FetchContent on non-Windows platforms; Windows uses vcpkg.
 - The CMake install produces a `find_package(LiveKit CONFIG)`-compatible package with `LiveKitConfig.cmake`, `LiveKitTargets.cmake`, and `LiveKitConfigVersion.cmake`.
 
-### Readability and Performance
-
-Code should be easy to read and understand. If a sacrifice is made for performance or readability, it should be documented.
-
-Adhere to clang-format checks configured in `.clang-format`. After C++ code changes, run `./scripts/clang-format.sh` to confirm styling, or `./scripts/clang-format.sh --fix` to auto-format.
-
-### Static Analysis
-
-Adhere to clang-tidy checks configured in `.clang-tidy`. After C++ code changes, run `./scripts/clang-tidy.sh` to confirm code quality.
-
 ## Dependencies
 
 | Dependency | Scope | Notes |
@@ -340,6 +332,7 @@ Adhere to clang-tidy checks configured in `.clang-tidy`. After C++ code changes,
 | spdlog | **Private** | FetchContent or system package; must NOT leak into public API |
 | nlohmann/json | **Private** | Header-only; vendored via FetchContent (Unix) or vcpkg (Windows); must NOT leak into public API |
 | client-sdk-rust | Build-time | Git submodule, built via cargo during CMake build |
+| cpp-tools | Developer / CI | Git submodule containing shared LiveKit C++ formatting and static-analysis tooling |
 | Google Test | Test only | FetchContent in `src/tests/CMakeLists.txt` |
 
 When adding a new private/vendored dependency to this table, also add a
@@ -372,13 +365,6 @@ Integration tests (`src/tests/integration/`) cover: room connections, callbacks,
 When adding new client facing functionality, add a new test case to the existing test suite.
 When adding new client facing functionality, add benchmarking to understand the limitations of the new functionality.
 
-## General C++ Development
-
-- Do not use dynamic memory allocation after initialization
-- Keep each function short (roughly ≤ 60 lines)
-- Declare all data objects at the smallest possible level of scope
-- Each calling function must check the return value of nonvoid functions, and each called function must check the validity of all parameters provided by the caller
-
 ## Common Pitfalls
 
 - A `Room` with `auto_subscribe = false` will never receive remote audio/video frames — this is almost never what you want.
@@ -398,8 +384,9 @@ all filtered stages; normal pull requests and pushes use the path filters.
 - `.github/workflows/builds.yml` — Reusable SDK and example-collection build
   matrix.
 - `.github/workflows/tests.yml` — Reusable unit/integration test matrix.
-- `.github/workflows/cpp-checks.yml` — Reusable `clang-format` and
-  `clang-tidy` checks.
+- `.github/workflows/cpp-tools.yml` — Reusable SDK-specific `clang-format` and
+  `clang-tidy` workflow. It prepares the build environment and invokes the
+  project wrappers backed by the shared `cpp-tools` scripts.
 - `.github/workflows/generate-docs.yml` — Reusable Doxygen docs validation.
 - `.github/workflows/rust-release-check.yml` — Reusable check that the pinned
  `client-sdk-rust` submodule commit maps to a published release. Gated by the
@@ -423,9 +410,10 @@ When adding or renaming files that affect a CI stage, update the matching
 `ci.yml` `changes` filter in the same PR. For example, new build scripts,
 CMake files, package manifests, or reusable build workflows should be added to
 the `builds` filter; test-only helpers to `tests`; formatting/static-analysis
-configuration to `cpp_checks`; and docs generation inputs to `docs`.
+configuration (including `cpp-tools` submodule bumps) to `cpp_tools`; and docs
+generation inputs to `docs`.
 
 Keep broad agent guidance files such as `AGENTS.md` out of the expensive
-`builds`, `tests`, `cpp_checks`, and `docs` filters unless they start affecting
+`builds`, `tests`, `cpp_tools`, and `docs` filters unless they start affecting
 generated docs or build artifacts. An `AGENTS.md`-only change should not trigger
 those stages; only the always-on cheap checks should run.

README.md

@@ -244,15 +244,23 @@ local `livekit-server --dev`, and run via `ctest` or directly. See
 
 ## Developer tools
 
-`clang-tidy`, `clang-format`, `valgrind`, and Doxygen are all wired up via
-scripts under `scripts/`. Set up the pre-commit auto-formatter
-with:
+This project uses `clang-tidy` and `clang-format` with shared configuration and
+wrapper scripts from the `cpp-tools` submodule. Install the tool executables
+separately, as described in [docs/tools.md](docs/tools.md), then create the
+root-level configuration symlinks with:
 
 ```bash
-./scripts/install-pre-commit.sh
+./cpp-tools/install.sh
 ```
 
-See [docs/tools.md](docs/tools.md).
+The pre-commit auto-formatter is opt-in:
+
+```bash
+./cpp-tools/install.sh precommit-hook
+```
+
+`valgrind`, Doxygen, and the complete developer-tool setup are also documented
+in [docs/tools.md](docs/tools.md).
 
 ## Deprecation
 

docs/tools.md

@@ -5,10 +5,14 @@ are also enforced in CI on PRs.
 
 ## Clang tools
 
-- **`clang-tidy`** — static analysis. See [.clang-tidy](https://github.com/livekit/client-sdk-cpp/blob/main/.clang-tidy) for the
+The shared configuration and tooling scripts come from the
+[`livekit/cpp-tools`](https://github.com/livekit/cpp-tools) submodule.
+
+- **`clang-tidy`** — static analysis. See
+  [cpp-tools/.clang-tidy](https://github.com/livekit/cpp-tools/blob/main/.clang-tidy) for the
   enabled checks. Enforced in CI on PR.
 - **`clang-format`** — code formatting and style consistency. See
-  [.clang-format](https://github.com/livekit/client-sdk-cpp/blob/main/.clang-format) for the rules. Enforced in CI on PR.
+  [cpp-tools/.clang-format](https://github.com/livekit/cpp-tools/blob/main/.clang-format) for the rules. Enforced in CI on PR.
 
 > **Note (Windows):** `clang-tidy` is not currently driven by our scripts on
 > Windows. The MSBuild CMake generator doesn't emit
@@ -34,6 +38,12 @@ ask you to add `/opt/homebrew/opt/llvm/bin` (Apple Silicon) or
 sudo apt-get install clang-format clang-tidy clang-tools
 ```
 
+Install the shared configuration symlinks from the repository root:
+
+```bash
+./cpp-tools/install.sh
+```
+
 ### Run `clang-tidy`
 
 1. Generate `compile_commands.json` and the protobuf headers via a release build:
@@ -86,7 +96,7 @@ A simple pre-commit hook that auto-formats staged C/C++ files using the
 project's `.clang-format` rules:
 
 ```bash
-./scripts/install-pre-commit.sh
+./cpp-tools/install.sh precommit-hook
 ```
 
 This installs `.git/hooks/pre-commit`. Re-run after `git clone` on a fresh