Configuration

Category: Explanation

Byte's configuration is straightforward and declarative. You define your preferences in a single JSONC file at .byte/config.jsonc, and Byte loads it at startup. Configuration is organized into sections—documentation framework, LLM models, linting, files, web, git, gateway, terminal UI, and presets. Invalid config produces clear error messages; changes take effect on the next invocation.

The Config File

Configuration lives at .byte/config.jsonc in your project root. It's JSON with comments—use // for single-line notes, /* */ for blocks. This is where you tell Byte how to behave.

When you run any Byte command, the config is loaded and validated. If something is wrong—a typo, an invalid value, a missing required field—Byte reports the error clearly and exits. Fix the problem and run again. Changes take effect immediately on the next invocation; no restart needed.

Configuration Sections

Configuration is organized into these sections:

documentation — Your documentation framework (mkdocs, vitepress, docusaurus, sphinx), whether Mermaid diagrams are enabled, and any additional writing guidelines.

files — File discovery patterns, which AI comment markers to watch for (AI:, AI@, AI?, AI!), and gitignore-style patterns for files Byte should ignore.

gateway — WebSocket JSON-RPC 2.0 gateway server: whether to enable it, what host to bind to, and which port to use.

git — Conventional commit behavior: commit scope selection, breaking change detection, and message guidelines.

lint — Linting and formatting commands: which commands to run and which file types they handle.

llm — LLM model assignment for four task types: fast (quick tasks), standard (general-purpose), reasoning (complex analysis), and coding (code generation).

presets — Predefined context and prompt presets: files to load automatically, conventions to apply, and features to enable.

tui — Terminal UI: color theme (Catppuccin variants) and code syntax highlighting preference.

web — Web browser automation: Chrome/Chromium binary location and feature toggles.

Example Configuration

Here's a minimal configuration that works out of the box:

{
  "$schema": "https://raw.githubusercontent.com/UseTheFork/byte/refs/heads/main/schema.json",
  "documentation": {
    "framework": "mkdocs",
  },
  "llm": {
    "fast": {
      "model": "claude-haiku-4-5",
      "provider": "anthropic",
    },
    "standard": {
      "model": "claude-sonnet-4-6",
      "provider": "anthropic",
    },
    "reasoning": {
      "model": "claude-opus-4-6",
      "provider": "anthropic",
    },
    "coding": {
      "model": "claude-haiku-4-5",
      "provider": "anthropic",
    },
  },
}

The $schema field enables validation and autocomplete in most editors.

Finding Configuration Options

The full configuration reference is rendered inline below. Every available setting, its type, default value, and what it controls is documented here — no need to go elsewhere.

Documentation

Documentation framework, features, and writing style configuration

Field	Type	Default	Description
enable_mermaid	boolean	true	Use Mermaid for diagrams and charts
framework	string	mkdocs	Documentation framework (e.g. mkdocs, vitepress, docusaurus, sphinx)
extra_guidelines	array[string]	-	Additional documentation guidelines
style	string	diataxis	Documentation writing style (e.g. diataxis, google, microsoft, minimal)

Files

File discovery, watching, and ignore pattern configuration

Field	Type	Default	Description
ignore	array[string]	['.byte', '.ruff_cache', '.idea', '.venv', '.env', '.git', '.pytest_cache', '__pycache__', 'node_modules', 'dist']	List of gitignore-style patterns to exclude from file discovery. Patterns support wildcards and are combined with .gitignore rules.

Files > Watch

Field	Type	Default	Description
enable	boolean	false	Enable file watching for AI comment markers (AI:, AI@, AI?, AI!). When enabled, Byte automatically detects changes and processes AI instructions.

Gateway

WebSocket JSON-RPC 2.0 gateway server configuration

Field	Type	Default	Description
enable	boolean	false	Whether the gateway server starts at boot
host	string	127.0.0.1	Hostname to bind the gateway server to
port	integer	0	Port to bind the gateway server to (0 lets the OS choose an available port)

Git

Git operations and conventional commit behavior configuration

Field	Type	Default	Description
enable_scopes	boolean	false	Enable scope selection for conventional commits
enable_breaking_changes	boolean	false	Enable breaking change detection and confirmation
enable_body	boolean	true	Enable commit message body generation
scopes	array[string]	-	Available scopes for conventional commits
description_guidelines	array[string]	-	Additional guidelines for commit descriptions
max_description_length	integer	72	Maximum character length for commit descriptions

Lint

Code linting and formatting configuration

Field	Type	Default	Description
enable	boolean	false	Enable or disable the linting functionality
commands	array[LintCommand]	[]	List of lint commands to run on files with their target extensions

Lint > LintCommand

Field	Type	Default	Description
command	array[string]	-	Command and arguments to execute for linting (e.g., ['ruff', 'check', '--fix']). Use {file} placeholder to specify where the file path should be inserted, otherwise it will be appended to the end.
languages	array[string]	-	List of language names this command handles (e.g., ['python', 'php']). Empty list means all files.

Llm

LLM provider and model assignment configuration

Field	Type	Default	Description

Llm > Fast

Field	Type	Default	Description
model	string	-	The model identifier to use
provider	string	-	The models provider to use
extra_params	object	-	Additional parameters to pass to the model initialization

Llm > Standard

Field	Type	Default	Description
model	string	-	The model identifier to use
provider	string	-	The models provider to use
extra_params	object	-	Additional parameters to pass to the model initialization

Llm > Reasoning

Field	Type	Default	Description
model	string	-	The model identifier to use
provider	string	-	The models provider to use
extra_params	object	-	Additional parameters to pass to the model initialization

Llm > Coding

Field	Type	Default	Description
model	string	-	The model identifier to use
provider	string	-	The models provider to use
extra_params	object	-	Additional parameters to pass to the model initialization

Presets

Predefined context and prompt presets

Field	Type	Default	Description
id	string	-	Unique identifier for the preset, used in /preset command
read_only_files	array[string]	-	Files to add to read-only context
editable_files	array[string]	-	Files to add to editable context
conventions	array[string]	-	Convention files to load
prompt	string | null	-	Preset prompt to load into chat input
load_on_boot	boolean	false	Automatically load this preset when byte starts

Tui

Terminal UI theme and syntax highlighting configuration

Field	Type	Default	Description
ui_theme	mocha, macchiato, latte, frappe	mocha	Catppuccin theme variant for the CLI interface (mocha/macchiato are dark, latte is light, frappe is cool dark)
syntax_theme	github-dark, bw, sas, staroffice, xcode, monokai, lightbulb, rrt	monokai	Pygments theme for code block syntax highlighting in CLI output

Web

Web browser automation and scraping configuration

Field	Type	Default	Description
enable	boolean	false	Enable web commands
chrome_binary_location	string | null	-	Path to Chrome/Chromium binary executable for headless browser automation

The reference above is organized by section. Find what you need by domain, then drop it into your .byte/config.jsonc.

Key Takeaways

1. Configuration is declarative — Define it in .byte/config.jsonc, and Byte respects it
2. It's organized by section — Find what you need by domain (llm, git, lint, etc.)
3. It's validated at load time — Invalid config produces clear error messages
4. Changes take effect on next invocation — No restart required
5. Full reference is available — See the settings reference for every option