Shell completions — Developer guide

This document is intended for implementors who want to add or maintain shell completion support in gmuse. The canonical, detailed implementation notes for Zsh are kept in specs/002-zsh-completions/spec.md — use that spec as the single source of truth for any compatibility or protocol requirements.

Runtime helper contract

Completion scripts should invoke the runtime helper gmuse git-completions-run with arguments --shell <shell> --for "git commit -m" and expect a JSON response of the form:

{
  "suggestion": "feat: add login",
  "status": "ok",
  "metadata": {
    "truncated": false,
    "elapsed_ms": 1200
  }
}

Status values: ok, timeout, offline, no_staged_changes, error.

Completion scripts must:

• Parse suggestion and insert it into the appropriate argument or buffer location for the target shell.

• Inspect status and implement reasonable fallbacks (e.g., show a short warning when no_staged_changes is returned).

• Treat the metadata fields as auxiliary for observability and logging.

Implementation checklist

• Implement a completion script for the target shell that:

  • Calls gmuse git-completions-run --shell <shell> --for "git commit -m"

  • Parses the returned JSON and extracts suggestion and status

  • Inserts the suggestion only when appropriate (e.g., when the message argument is empty)

  • Falls back to the shell’s normal completion behavior when needed

• Add or update automated tests where possible (unit tests for parsing, integration tests that exercise gmuse git-completions-run and the completion script in a controlled environment).

• Document installation and usage in docs/source/how_to/completions.md by adding the shell to the Supported shells section and linking to this developer guide for implementors.

• If the new shell requires special contract extensions or behaviors, add or extend a spec under specs/ and reference it from this guide.

Zsh notes & testing

• The current Zsh implementation keeps the completion script dependency-free and uses small sed expressions instead of jq to extract the minimal JSON fields. Other shells may choose different strategies.

• For local testing of the runtime helper, run:

GMUSE_DEBUG=1 gmuse git-completions-run --shell zsh --for "git commit -m" --timeout 3.0

(adjust --shell and other args as needed for the target shell).

Contributing & specs

• For Zsh-specific low-level details, see: specs/002-zsh-completions/spec.md.

• Prefer updating the spec for any contract changes and link the spec from this guide to avoid duplication.

• When opening a PR, include tests and a short usage example in docs/ for the new shell.