Feature Flags

Zeph uses Cargo feature flags to control optional functionality. The remaining optional features are organized into use-case bundles for common deployment scenarios, with individual flags available for fine-grained control.

Use-Case Bundles

Bundles are named Cargo features that group individual flags by deployment scenario. Use a bundle to get a sensible default for your use case without listing individual flags.

Bundle build examples

cargo build --release --features desktop          # TUI agent for daily use
cargo build --release --features ide              # IDE assistant (ACP)
cargo build --release --features server           # headless server/daemon
cargo build --release --features desktop,server   # combined: TUI + server
cargo build --release --features ml               # local model inference
cargo build --release --features ml,metal         # local inference with Metal GPU (macOS)
cargo build --release --features ml,cuda          # local inference with CUDA GPU (Linux)
cargo build --release --features full             # all optional features (CI / release builds)
cargo build --release --features full,ml          # everything including local inference

Bundles are purely additive. All existing --features tui,scheduler style builds continue to work unchanged.

No cli bundle: the default build (cargo build --release, no features) already represents the minimal CLI use case. A separate cli bundle would be a no-op alias.

Built-In Capabilities (always compiled, no feature flag required)

The following capabilities compile unconditionally into every build. They are not Cargo feature flags — there is no #[cfg(feature)] gate and no way to disable them. They are listed here for reference only.

Optional Features

Crate-Level Features

Some workspace crates expose their own feature flags for fine-grained control:

ACP session management (unstable)

The unstable-session-* flags gate ACP session lifecycle handlers and IDE integration features that depend on draft ACP spec additions. They are enabled by default but the API surface may change before the spec stabilises. Each flag also enables the corresponding feature in agent-client-protocol so the SDK advertises the capability during initialize.

The acp feature in the root crate automatically enables all unstable-session-* flags in zeph-acp. There is no separate acp-unstable flag.

Disable all session management flags to build a minimal ACP server without them:

cargo build -p zeph-acp --no-default-features

Disable the schema feature to compile zeph-llm without schemars:

cargo build -p zeph-llm --no-default-features

Build Examples

cargo build --release                                      # default build (scheduler + sqlite + always-on features)
cargo build --release --features desktop                   # TUI dashboard
cargo build --release --features ide                       # ACP (includes all unstable-session-* flags)
cargo build --release --features server                    # gateway + a2a + otel
cargo build --release --features desktop,server            # combined desktop and server
cargo build --release --features ml,metal                  # local inference with Metal GPU (macOS)
cargo build --release --features ml,cuda                   # local inference with CUDA GPU (Linux)
cargo build --release --features full                      # all optional features (except candle/metal/cuda)
cargo build --release --features tui                       # individual flag still works
cargo build --release --features tui,a2a                   # combine individual flags freely

The full feature enables every optional feature except candle, metal, and cuda (hardware-specific, opt-in).

Build Profiles

Build with the CI profile:

cargo build --profile ci

zeph-index Language Features

Tree-sitter grammars are controlled by sub-features on the zeph-index crate (always-on). All are enabled by default.