This guide is for developers who want to build, extend, or contribute to Flock itself.
Flock CI builds against DuckDB v1.5.4. User-facing docs require DuckDB 1.5.0+.

​
Local Development Setup

  • Clone the repository:
  • Initialize submodules (if you forgot --recursive):
  • Build and run via helper script:
The interactive script will:
  • Check for required tools (CMake, compiler, Ninja/Make, etc.).
  • Configure dependencies via vcpkg.
  • Build Flock (Debug/Release).
  • Launch DuckDB with the Flock extension preloaded.
See the root README.md for a concise overview of these steps. For a CLion-specific walkthrough (open the DuckDB CMake project, vcpkg, and run configs), see docs/development/clion.md in the repository. That guide is not part of this docs site.

​
Building the Extension Manually

While ./scripts/build_and_run.sh is the recommended path, you can also build manually:
The resulting Flock extension library can then be loaded from DuckDB using LOAD with the appropriate path.

​
WASM builds

Flock CI produces DuckDB-WASM extension artifacts via extension-ci-tools (see .github/workflows/MainDistributionPipeline.yml). To build locally:
  1. Clone with submodules and follow the steps above.
  2. Use the extension distribution toolchain with WASM_EXTENSIONS=1 and an Emscripten target, following the patterns in extension-ci-tools/.github/workflows/_extension_distribution.yml.
Published WASM binaries ship through DuckDB’s extension repository when released to the community catalog. For install commands and browser limitations, see Installation.

​
Running Tests

Flock comes with both unit and integration tests:
  • C++ unit tests live under test/unit/.
  • Integration tests (Python + DuckDB) live under test/integration/.
Example pattern (from the repo root):
Check the repository’s CI configuration for the exact commands used in automation.

​
Coding Conventions

When contributing code:
  • Follow the surrounding C++ style (namespaces, includes, brace style).
  • Avoid introducing new dependencies without a clear reason.
  • Prefer small, focused pull requests with clear descriptions.
If in doubt, mirror patterns used in existing functions such as llm_complete or the metrics manager.

​
Working on Providers & Models

  • Provider-specific adapters live under src/model_manager/providers/adapters/.
  • HTTP and batching logic is centralized in provider handlers under src/include/flock/model_manager/providers/handlers/.
  • New providers should:
    • Integrate with the existing metrics API.
    • Respect the context_columns abstraction.
    • Provide clear, actionable error messages when a feature is unsupported.
For examples, see the existing OpenAI, Azure, Ollama, and Anthropic adapters.

​
Docs & Developer Experience

The Mintlify docs live in docs/. Install the CLI once:
There are two local preview workflows. Use both at different times — they are not interchangeable.

​
mint dev — fast editing

Best for writing and layout while you iterate on MDX, nav, and components.
Open http://localhost:3000.
  • Hot reload on save
  • Mintlify dev server (root URL, no /flock prefix)
  • Mintlify cloud search when the CLI is authenticated (optional)
  • Does not run the GitHub Pages export, path rewrites, or Pagefind index

​
build-and-serve.sh — production parity

Best before merging doc changes, when testing search, or when verifying links and assets under the GitHub Pages base path. From the repo root:
Open http://localhost:3000/flock/ (the /flock/ prefix matters). This script:
  1. mint export → static HTML
  2. prepare-github-pages.mjs → rewrites paths for /flock and injects the Pagefind search bridge
  3. pagefind → builds the client-side search index
  4. Serves the result with the same layout as GitHub Pages
Optional environment variables: PORT (default 3000), GITHUB_PAGES_BASE_PATH (default /flock), SITE_DIR, SITE_ZIP, DOCS_TMPDIR. If mint export fails with ENOSPC, set DOCS_TMPDIR=/tmp.
Cmd+K search on the static export uses Pagefind, not Mintlify cloud search. If search shows “Search is unavailable offline”, you are likely on mint dev or skipped the Pagefind step — use build-and-serve.sh instead.

​
When adding new Flock features, update

  • The home page (index.mdx) for high-level positioning
  • The relevant function or feature page (e.g. llm-complete.mdx modalities, llm-metrics.mdx)
  • static/llms.txt so entry points stay current
  • docs.json navigation if you add or regroup pages
  • This Developer Guide for build, testing, or contribution-related changes