Configure gmuse#

This guide shows you how to configure gmuse for common use cases. For complete configuration options, see the Configuration Reference.

Set up your first configuration#

Create a configuration file to set persistent preferences:

Create the config directory if it doesn’t exist:
```
mkdir -p ~/.config/gmuse
```

Create ~/.config/gmuse/config.toml with your preferences:

model = "gpt-4o-mini"
format = "conventional"
history_depth = 10

Test your configuration:
```
gmuse info
```

You should see your configured model and settings displayed.

Manage config from the CLI#

You can also view and update your global configuration without manually editing files:

$ gmuse config view

$ gmuse config set format conventional
$ gmuse config set history_depth 10

Notes:

gmuse config view shows the config file location, the file contents (if present), and an effective configuration table.
Environment variables (for example GMUSE_FORMAT) can override values stored in the config file.

Switch between LLM providers#

To use a different provider, set the appropriate API key; gmuse will auto-detect the provider from the environment.

For OpenAI:

$ export OPENAI_API_KEY="sk-..."
$ gmuse msg

For Anthropic Claude:

$ export ANTHROPIC_API_KEY="sk-ant-..."
$ gmuse msg --model claude-3-5-sonnet-20241022

For Google Gemini:

$ export GEMINI_API_KEY="..."
$ gmuse msg --model <model-name>

For local models such as Ollama, see Host a local model.

To set your default model, add it to your config file:

model = "claude-3-5-sonnet-20241022"

Change commit message format#

To use Conventional Commits format:

For one commit:

$ gmuse msg --format conventional

Persistently:

# ~/.config/gmuse/config.toml
format = "conventional"

For gitmoji style:

format = "gitmoji"

Adjust history context#

Control how many past commits gmuse uses as style examples:

Use more history for better style matching:

history_depth = 15

Disable history context:

history_depth = 0

Override for a single command:

$ gmuse msg --history-depth 20

Tune LLM generation parameters#

Control how the AI generates messages:

Temperature#

Temperature controls randomness (0.0 = deterministic, 2.0 = very creative):

For deterministic CI/CD environments:

temperature = 0.0

For creative messages (default is 0.7):

temperature = 1.2

Override for a single command:

$ gmuse msg --temperature 0.3

Maximum tokens#

Limit the length of generated messages:

max_tokens = 200  # Shorter messages

$ gmuse msg --max-tokens 100

Diff size limits#

Control how much code context is sent to the LLM:

max_diff_bytes = 50000  # Allow larger diffs (default: 20000)

$ gmuse msg --max-diff-bytes 10000  # Smaller limit

Use case: Large diffs may exceed API limits or increase costs. Adjust this based on your needs.

Other tunable parameters#

Configure via environment variables or config file:

max_message_length = 500    # Maximum commit message length (default: 1000)
chars_per_token = 4         # Token estimation heuristic (default: 4)

$ export GMUSE_MAX_MESSAGE_LENGTH=500
$ export GMUSE_CHARS_PER_TOKEN=3

Enable clipboard copying#

To automatically copy messages to your clipboard:

Install the clipboard extra:
```
$ pip install 'gmuse[clipboard]'
```
Enable in config:
```
copy_to_clipboard = true
```

Or use the --copy flag for one-time copying:

$ gmuse msg --copy

Set project-specific instructions#

For team-wide commit message conventions, create a .gmuse file in your repository root:

Create .gmuse in your project:

$ cat > .gmuse << 'EOF'
All commit messages must reference a Jira ticket in the format [PROJ-123].
Keep subject lines under 50 characters.
Use present tense for all messages.
EOF

Commit the file so the team can use it:

$ git add .gmuse
$ git commit -m "docs: add commit message guidelines"

Now gmuse will include these instructions in every prompt for this repository.

Increase timeout for slow networks#

If you’re experiencing timeout errors:

For all commands:

timeout = 120

For one command:

$ gmuse msg  # Uses GMUSE_TIMEOUT if set

Or set via environment:

$ export GMUSE_TIMEOUT=120
$ gmuse msg

Enable debug logging#

To troubleshoot issues:

Temporary debug mode:

$ GMUSE_DEBUG=1 gmuse msg

Debug to file:

$ export GMUSE_LOG_FILE=~/.cache/gmuse/debug.log
$ export GMUSE_DEBUG=1
$ gmuse msg

Warning: Debug logs may contain your code diffs and prompts. Don’t enable in sensitive environments.

Override config for testing#

Test different settings without changing your config file:

# Try a different model
$ gmuse msg --model gpt-4o --dry-run

# Test conventional format
$ gmuse msg --format conventional --dry-run
# Try with no history
$ gmuse msg --history-depth 0 --dry-run

The --dry-run flag shows you the prompt without calling the LLM.

Check your configuration#

To see what settings are active:

$ gmuse info

This shows:

Resolved model name
Detected provider
Which API keys are set
Environment variables in use