Configuration Reference#

Comprehensive reference of all configuration options and environment variables that affect gmuse’s behavior. For quick setup steps and common tasks, see the How‑to: Configure gmuse.

Configuration Hierarchy#

gmuse loads configuration from multiple sources with the following priority (highest to lowest):

  1. CLI flags — Command-line options passed to gmuse msg

  2. Environment variables — GMUSE_* variables

  3. User configuration file — Persistent user preferences

  4. Defaults — Built-in fallback values

User Configuration File#

gmuse loads persistent user-level configuration from:

Location: $XDG_CONFIG_HOME/gmuse/config.toml Fallback: ~/.config/gmuse/config.toml

Format: TOML with top-level keys (no section headers needed)

Example:

model = "gpt-4o-mini"
format = "conventional"
history_depth = 10
copy_to_clipboard = false
timeout = 60

Note: This is separate from repository-level instructions (see Repository Instructions below).

Manage Configuration via CLI#

gmuse provides commands to view and update the global config file:

$ gmuse config view
$ gmuse config set <key> <value>

gmuse config view prints:

  • the resolved global config file path

  • raw file contents (if the file exists)

  • an effective configuration table, including warnings when environment variables override file values

Configuration Options#

model#

Type: string Default: null (auto-detected based on provider) Environment variable: GMUSE_MODEL

LLM model identifier to use for generation. If not specified, gmuse selects a default model based on the detected provider:

  • openai → gpt-4o-mini

  • anthropic → claude-3-5-sonnet-20241022

  • gemini → gemini/gemini-flash-lite-latest

  • cohere → command

  • azure → gpt-4o

For providers without default models (such as bedrock and huggingface), you must specify a model explicitly using the model configuration option, GMUSE_MODEL environment variable, or the --model CLI flag. Otherwise, gmuse will raise an error with instructions.

Provider Detection: gmuse auto-detects the provider based on these environment variables:

Variable

Provider

OPENAI_API_KEY

OpenAI

ANTHROPIC_API_KEY

Anthropic

GEMINI_API_KEY or GOOGLE_API_KEY

Google Gemini

COHERE_API_KEY

Cohere

AZURE_API_KEY

Azure OpenAI

Run gmuse info to see which provider was detected.

model = "gpt-4o"

format#

Type: string Default: "freeform" Valid values: "freeform", "conventional", "gitmoji" CLI flag: --format, -f Environment variable: GMUSE_FORMAT

Commit message format style:

  • freeform — Natural language messages with no specific structure

  • conventional — Conventional Commits format (type(scope): description)

  • gitmoji — Messages prefixed with relevant emoji

format = "conventional"

history_depth#

Type: integer Default: 5 Valid range: 0 to 50 CLI flag: --history-depth Environment variable: GMUSE_HISTORY_DEPTH

Number of recent commits to include in the prompt as style examples. Set to 0 to disable commit history context.

history_depth = 10

timeout#

Type: integer (seconds) Default: 30 Valid range: 5 to 300 Environment variable: GMUSE_TIMEOUT

Request timeout for LLM API calls in seconds.

timeout = 60

copy_to_clipboard#

Type: boolean Default: false CLI flag: --copy, -c Environment variable: GMUSE_COPY (accepts "1", "true", "yes")

Automatically copy generated commit messages to the system clipboard.

copy_to_clipboard = true

Requirements: Requires the optional gmuse[clipboard] extra (provides pyperclip) and a system clipboard utility (pbcopy, xclip, or wl-copy).

learning_enabled#

Type: boolean Default: false Environment variable: GMUSE_LEARNING (accepts "1", "true", "yes")

Status: Experimental (not yet implemented)

When enabled, gmuse will learn from your commit message edits to improve future suggestions. Learning data will be stored in $XDG_DATA_HOME/gmuse/history.jsonl.

learning_enabled = false

Privacy note: Learning is opt-in and disabled by default. Learning data is stored locally only.

log_file#

Type: string (file path) Default: null Environment variable: GMUSE_LOG_FILE

Optional path to write debug logs. If not specified, logs are written to stderr. Supports tilde (~) expansion.

log_file = "~/.cache/gmuse/debug.log"

Environment variable: Set GMUSE_DEBUG=1 to enable detailed logging for troubleshooting.

Security warning: When GMUSE_DEBUG=1 is enabled, prompts, diffs, and hints may appear in logs. Avoid enabling debug mode in sensitive environments. API keys are always redacted in logs.

LLM Generation Parameters#

temperature#

Type: float Default: 0.7 Valid range: 0.0 to 2.0 CLI flag: --temperature Environment variable: GMUSE_TEMPERATURE

Controls randomness in LLM output. Lower values (closer to 0.0) produce more deterministic, focused responses. Higher values (closer to 2.0) produce more creative, varied responses.

temperature = 0.3  # More deterministic

Use cases:

  • 0.0-0.3: Deterministic CI/CD environments, reproducible messages

  • 0.5-0.9: Balanced creativity and consistency (default: 0.7)

  • 1.0-2.0: More creative, varied messages

max_tokens#

Type: integer Default: 500 Valid range: 1 to 100000 CLI flag: --max-tokens Environment variable: GMUSE_MAX_TOKENS

Maximum number of tokens the LLM can generate in its response. Shorter values produce more concise messages.

max_tokens = 200  # Shorter messages

Note: Most commit messages use 20-100 tokens. The default of 500 provides plenty of room.

max_diff_bytes#

Type: integer Default: 20000 (approximately 5000 tokens) Valid range: 1000 to 10000000 CLI flag: --max-diff-bytes Environment variable: GMUSE_MAX_DIFF_BYTES

Maximum size of the diff (in bytes) to include in the prompt. If the staged diff exceeds this limit, it will be truncated.

max_diff_bytes = 50000  # Allow larger diffs

Use cases:

  • Large refactorings may need higher limits

  • API rate limits or costs may require lower limits

  • You’ll see a warning if truncation occurs

max_message_length#

Type: integer Default: 1000 Valid range: 10 to 10000 Environment variable: GMUSE_MAX_MESSAGE_LENGTH

Maximum allowed length for generated commit messages (in characters). Messages exceeding this length will be rejected with a validation error.

max_message_length = 500  # Shorter maximum

max_chars (optional override)#

Type: integer or null Default: null (unset) Valid range: 1 to 500 Environment variable: GMUSE_MAX_CHARS

Optional setting to impose a strict maximum character limit for generated commit messages. When set, max_chars takes precedence over max_message_length for validation and is included in the prompt so the LLM is instructed to produce a message within that limit.

# Enforce a short, strict subject length
max_chars = 50

chars_per_token#

Type: integer Default: 4 Valid range: 1 to 10 Environment variable: GMUSE_CHARS_PER_TOKEN

Heuristic used for token estimation (approximately 4 characters per token for GPT models). Adjust this if using models with different tokenization.

chars_per_token = 3  # For models with denser tokenization

Note: This is a rough approximation. Actual token counts vary by model and text content.

Repository Instructions#

In addition to user-level configuration, gmuse supports repository-level instructions that are committed to the project and shared with all contributors.

Location: .gmuse file in repository root

The .gmuse file contains plain text instructions that are injected directly into the LLM prompt. This is useful for team-wide conventions like:

  • “Always reference a Jira ticket ID”

  • “Keep subject lines under 50 characters”

  • “Use past tense for commit messages”

Example .gmuse file:

All commit messages must reference a ticket ID in the format [PROJ-123].
Keep subject lines under 50 characters.

Note: The .gmuse file is for prompt instructions, not configuration options. Configuration options must be in the user config file.

See also#

On this page
Edit on GitHub
Show Source