gmuse.cli.completions

CLI commands for shell completions.

This module provides shell completion support for gmuse, including:

• A command to emit shell-specific completion scripts

• A runtime helper that generates AI suggestions for commit messages

Commands:

git-completions: Group command for completion-related subcommands git-completions zsh: Emit the zsh completion script to stdout git-completions-run: Runtime helper called by shell completion functions

Example:

>>> # Add to ~/.zshrc:
>>> # eval "$(gmuse git-completions zsh)"

Module Contents

Classes

CompletionStatus	Status codes for completion responses.
CompletionRequest	Represents the input context for generating a commit message.
CompletionResponse	Represents the output from the runtime helper.

Functions

_load_zsh_template	Load the zsh completion template from package resources.
completions_zsh	Emit the zsh completion script to stdout.
completions_run_command	Runtime helper for shell completions.

Data

logger
completions_app

API

gmuse.cli.completions.logger = 'get_logger(...)'

gmuse.cli.completions.completions_app = 'Typer(...)'

class gmuse.cli.completions.CompletionStatus

Bases: str, enum.Enum

Status codes for completion responses.

Attributes:

OK: Suggestion generated successfully. TIMEOUT: Generation timed out. OFFLINE: Network unavailable or credentials missing. NO_STAGED_CHANGES: No staged changes found. ERROR: Internal error.

Initialization

Initialize self. See help(type(self)) for accurate signature.

OK = 'ok'

TIMEOUT = 'timeout'

OFFLINE = 'offline'

NO_STAGED_CHANGES = 'no_staged_changes'

ERROR = 'error'

class gmuse.cli.completions.CompletionRequest

Represents the input context for generating a commit message.

Attributes:

staged_diff: The staged changes from git diff –staged. timeout: Timeout in seconds for the generation.

staged_diff: str = None

timeout: float = 3.0

class gmuse.cli.completions.CompletionResponse

Represents the output from the runtime helper.

Attributes:

suggestion: The generated commit message (empty if error). status: Status code indicating success or failure mode. metadata: Additional info such as truncated flag and elapsed time.

suggestion: str = None

status: gmuse.cli.completions.CompletionStatus = None

metadata: dict[str, object] = None

to_json() → str

Serialize response to JSON string.

Returns:

JSON string representation of the response.

gmuse.cli.completions._load_zsh_template() → str

Load the zsh completion template from package resources.

Raises:

RuntimeError: If the template cannot be read.

gmuse.cli.completions.completions_zsh() → None

Emit the zsh completion script to stdout.

The script provides AI-generated commit message suggestions when completing ‘git commit -m’. Add to your ~/.zshrc using eval.

Example:

eval “$(gmuse git-completions zsh)”

gmuse.cli.completions.completions_run_command(shell: str = typer.Option(..., '--shell', help='The target shell (e.g., zsh)'), for_command: str = typer.Option(..., '--for', help="The command being completed (e.g., 'git commit -m')"), timeout: float = typer.Option(3.0, '--timeout', help='Timeout in seconds')) → None

Runtime helper for shell completions.

This command is called by shell completion functions to generate AI-powered commit message suggestions. It outputs JSON to stdout.

Args:

shell: The target shell. Currently only “zsh” is supported. for_command: The command being completed. Expected to contain “git commit”. timeout: Timeout in seconds for LLM generation.

The output format is:

{“suggestion”: “…”, “status”: “ok|timeout|offline|no_staged_changes|error”, “metadata”: {…}}

Note:

Debug logging for completions requires log_file to be configured. Set log_file in config.toml or via GMUSE_LOG_FILE environment variable. Example: log_file = “~/.cache/gmuse/debug.log”