common

Active contributors: Georgi Gerganov, Sigbjørn Skjæret, Daniel Bevenius, Xuan-Son Nguyen, CISC, aldehir, angt, pwilkin

common/ is the shared C++ library that every in-tree binary tool links against. It is not part of the public C API — downstream library consumers should not depend on it — but inside the repo it does the heavy lifting of argument parsing, downloading, sampling defaults, chat templating, console I/O, and tool-call parsing.

Purpose

• One canonical place for "stuff every llama-* binary needs."
• Hide the complexity of cross-platform CLI handling, downloads, and Jinja templating from individual tools.

Directory layout

common/
├── arg.cpp / .h               # The big one (~189 KB) — argv → common_params
├── common.cpp / .h            # common_init_from_params, helpers (~66 KB)
├── sampling.cpp / .h          # canonical sampler chain, presets
├── preset.cpp / .h            # named CLI presets (-cnv, --reasoning, ...)
├── chat.cpp / .h              # Jinja-based chat template rendering (~103 KB)
├── chat-auto-parser.h         # Streaming tool-call parser (~17 KB)
├── chat-auto-parser-helpers.{cpp,h}
├── chat-auto-parser-generator.cpp
├── chat-peg-parser.{cpp,h}    # PEG-based chat extraction
├── chat-diff-analyzer.cpp     # Streaming output diff helper
├── peg-parser.{cpp,h}         # General-purpose PEG engine (~82 KB)
├── jinja/                     # Vendored google/minja port
├── console.cpp / .h           # Cross-platform interactive console
├── log.cpp / .h               # Logging macros + level routing
├── debug.cpp / .h             # Debug helpers
├── download.cpp / .h          # libcurl-based downloads
├── hf-cache.cpp / .h          # HuggingFace cache (~24 KB)
├── http.h                     # Tiny HTTP client used by download.cpp
├── speculative.cpp / .h       # Speculative-decoding driver
├── ngram-cache.{cpp,h}, ngram-map.{cpp,h}, ngram-mod.{cpp,h}
├── llguidance.cpp             # llguidance grammar shim (build-gated)
├── json-partial.cpp / .h      # Streaming JSON parser
├── json-schema-to-grammar.{cpp,h}
├── reasoning-budget.{cpp,h}   # "Thinking" tag handling
├── regex-partial.{cpp,h}      # Streaming regex helpers
├── fit.{cpp,h}                # Curve fitting (used by tools/fit-params)
├── unicode.{cpp,h}            # Companion to src/unicode.* — used in common only
├── base64.hpp                 # Single-header base64
├── build-info.cpp.in          # Configured at build time with git commit
└── build-info.h

Most-used pieces

common_params and arg.cpp

common/common.h defines common_params, the giant struct that holds every CLI flag the project supports. common/arg.cpp declares each option as a common_arg (name, env var, help text, parser callback) and registers it under the relevant tool group. Because arg.cpp is shared, every binary tool exposes the same flag set with the same names — --n-gpu-layers works the same in llama-cli, llama-server, and llama-bench.

common_init_from_params

A one-call constructor that takes a populated common_params and returns a fully-initialized (llama_model, llama_context). It handles -hf downloads, mmap policy, KV cache types, RoPE settings, LoRA loading, GPU layer placement, and pooling configuration. Most tools just call it and move on.

common_sampler (sampling.cpp)

Builds the canonical sampler chain (penalties → DRY → top-k → typical → top-p → min-p → xtc → temp(_ext) → grammar → dist) from common_params. See Sampler.

common/chat.cpp + common/jinja/

Renders chat messages using either the GGUF-embedded Jinja template or one of the built-in formats. Returns a single prompt string ready to tokenize. See Chat templates.

common/download.cpp + common/hf-cache.cpp

Implements the -hf <repo> flag. Downloads model files into the standard HuggingFace cache directory, with progress display, resume support, and SHA-256 verification. Requires LLAMA_CURL=ON at build time; tools degrade gracefully without it.

common/console.cpp

Cross-platform raw-mode console handling. Owns the input loop in interactive llama-cli, including line editing, multi-line input, history, and color output.

common/log.cpp

The tools' logging frontend. Defines LOG_INF/LOG_WRN/LOG_ERR/LOG_DBG macros that route through a single back-end with level filtering, color coding, and optional file output.

Integration points

• Tools. Every tools/*/CMakeLists.txt links the common target.
• Examples. Most examples/* reuse common for argv handling.
• libllama — common depends on it but not vice versa. The library itself never imports common.
• Vendored dependencies. nlohmann/json, cpp-httplib, minja, base64, stb_image, llguidance (Rust) all live under vendor/. common includes them as needed.

Entry points for modification

• Add a CLI flag. Edit common/arg.cpp and add the corresponding field to common_params in common/common.h. Don't add a per-tool flag unless it really only applies to one tool.
• Add a new sampler default. common/sampling.cpp::common_sampler_init.
• Improve Jinja parity. common/jinja/. Add a regression test in tests/test-chat-template.cpp.
• New download backend. common/download.cpp. Currently only HuggingFace is supported via -hf; --model-url accepts arbitrary URLs.