Skip to content

Latest commit

 

History

History
225 lines (155 loc) · 28.8 KB

configuration.md

File metadata and controls

225 lines (155 loc) · 28.8 KB

Configuration

Documentation index · CLI reference · Versioning

Configure a Provider

Verify the endpoint before supplying a new key or starting key-bearing model discovery. The model picker can contact the provider using an existing or newly entered key before the full wizard saves. Qwen asks for its exact plan/region endpoint before the key; other providers use a remembered/default endpoint without an endpoint prompt in the wizard. Check the destination again after switching providers because profile-reset limitations can expose a previously configured URL. Keep the intended endpoint explicitly nonblank; client construction rejects a missing endpoint rather than falling back to an unrelated host.

For a custom, stale, or untrusted profile, use this order before entering credentials or opening the model picker:

  1. Select the target provider without catalog discovery, for example git-tools settings provider openai --non-interactive (replace openai with your provider). This saves the provider/profile settings without opening the wizard.
  2. Confirm the target provider is effective and reconcile exported provider/endpoint overrides and stale local git-tools.env values. Then set the intended URL with git-tools settings api-base <URL> and inspect the effective API Endpoint in git-tools settings; an exported endpoint still overrides a newly saved URL.
  3. Only after verifying the destination, use the masked git-tools settings api-key editor and then Main Model, or run the full provider wizard for that same provider.

Once the endpoint is verified, open settings:

git-tools settings

Choose Provider and follow the prompts:

  1. Select your provider.
  2. Enter its API key using the masked prompt. Qwen asks for its exact plan/region endpoint first.
  3. Choose the main model.
  4. Choose routing or thinking/reasoning options when offered. For a saved Kimi tier, explicitly select the intended tier rather than blindly accepting the picker's default.
  5. Complete the flow to save.

A blank API-key prompt keeps an existing/default key. Back revisits the previous step; canceling discards the unfinished wizard's pending settings and reverts temporary process endpoint/key changes. The full wizard saves only when completed, but cancellation does not undo discovery requests already sent or guarantee rollback of catalog-cache writes. Separately completed settings edits remain saved. The sections below explain provider-specific options and advanced configuration.

git-tools settings provider                     # Interactive provider selector and setup
git-tools settings provider openrouter          # Same wizard, starting with OpenRouter in a terminal
git-tools settings provider openrouter --interactive
git-tools settings provider openrouter --non-interactive  # Save provider/defaults without prompts

Named-provider commands automatically use the wizard in a terminal and retain non-interactive behavior without a terminal. Explicit flags override that choice. API Key and Main Model can also be edited separately afterward. Endpoints, default models and curated choices are defined by the upstream-derived modules in git_tools/providers/ and git-tools' registry integration; they are defaults, not allowed-model whitelists. Use Esc or ← Back to return a level; standalone settings ends with Done, while settings opened from the root menu ends with ← Back. Text/password prompts have no Back row, and searchable filtering may hide a list's Back option; Esc remains available. Prefer the masked credential prompt over secret command arguments.

Provider Credential variable Default endpoint Default model
openrouter OPENROUTER_API_KEY https://openrouter.ai/api/v1 deepseek/deepseek-v4-flash-0731
kimicode (kimicli) KIMICODE_API_KEY https://api.kimi.com/coding/v1 kimi-for-coding
cliproxyapi CLIPROXYAPI_API_KEY http://127.0.0.1:8317/v1 gpt-6-astra
acrc ACRC_API_KEY https://fmodel.ai.acrc.a-star.edu.sg/v1 deepseek-v4.1-flash
copilot COPILOT_API_KEY http://127.0.0.1:4141/v1 gpt-4.1 profile default; select a served model
qwen (qwencode) DASHSCOPE_API_KEY or QWENCODE_API_KEY Required explicit plan/region endpoint qwen3.8-max
openai OPENAI_API_KEY https://api.openai.com/v1 gpt-6-astra
anthropic (claude) ANTHROPIC_API_KEY https://api.anthropic.com/v1 claude-opus-5-5
zcode ZCODE_API_KEY https://api.z.ai/api/coding/paas/v4 glm-5.3

kimi and kimicode are aliases for the retained kimicli storage key; qwencode, dashscope, and alibaba resolve to the retained qwen key and its saved profiles. router, proxy, and claude are also accepted. Qwen accepts both credential variables; source precedence wins first, then DASHSCOPE_API_KEY wins over QWENCODE_API_KEY within one source. Likewise, QWENCODE_BASE_URL is an endpoint alias while profile saves retain QWEN_BASE_URL. The table records repository defaults, not current model availability or account access. All generation clients use OpenAI-compatible chat completions; Anthropic is also called through that compatibility interface, not its native Messages API. Confirm endpoint support and parameter acceptance with your service.

Alignment with agent-core

Compatible provider metadata, request branches, and ordinary reasoning-response helpers are lifted from agent-core and mapped through git-tools' existing settings/catalog wrapper. Shared provider defaults and request rules are source-compared by offline tests; this is not a copy of agent-core's full runtime. Fresh temperature defaults to 1.0, while existing saved or explicit values retain precedence. Missing endpoints are rejected before SDK construction. SDK retries are disabled so git-tools' existing outer retry loop owns attempts.

Intentional adaptations remain: saved kimicli/qwen profile keys and credential aliases, host-local proxy URLs, the extra Copilot provider, live/curated catalog UI without static fallback catalogs for live-discovery providers, and git-tools' output budgets and single-model workflow. The pinned SDK supports chat completions and non-streaming ordinary-message reasoning capture/replay; newer agent-core streaming hooks, checkpoint/v1 content-block conversion, Responses-only OpenAI routing, role/session routing, and deadline ladders are not imported. OpenRouter reasoning retains its native reasoning and reasoning_details fields rather than being renamed on the wire. The CLI displays returned reasoning_content or OpenRouter's plain-text reasoning when present; structured/encrypted reasoning_details stay opaque and are not rendered as text. A missing reasoning panel does not mean the service performed no reasoning.

Provider-specific request behavior

You can skip this section for ordinary setup. It explains which request parameters the clients send; model availability and parameter support still depend on your service.

The implementation classifies nonempty OpenAI-platform model IDs as reasoning-capable except IDs beginning with gpt-3, gpt-4, chatgpt-, o1-mini or o1-preview, or containing -chat (case-insensitive). For models classified as reasoning-capable, it sends a configured effort other than none; configured temperature is forwarded as in agent-core, subject to the pinned SDK and endpoint's model-specific handling. Unlisted OpenAI-platform IDs therefore receive a configured tier unless excluded; this is a client policy, not a guarantee that every server/model accepts it. CLIProxyAPI sends configured temperature and only an explicitly configured reasoning tier for IDs classified as OpenAI-family reasoning models by the repository's non-reasoning exclusions. ACRC and Copilot use the same OpenAI-family reasoning classification before forwarding a configured reasoning_effort; acceptance is endpoint/model-dependent. none omits the tier for OpenAI, CLIProxyAPI, Copilot, ACRC, Qwen and Kimi; OpenRouter forwards none as a tier. The Anthropic client omits temperature, sends thinking.type=disabled for none, and otherwise forwards a configured effort. Whether the service applies those fields is outside local validation. Kimi's picker uses catalog capabilities, while request construction follows the explicit settings described below.

ACRC VPN access and Copilot proxy authentication are managed externally. Host-local proxies default to loopback addresses; CLIProxyAPI intentionally uses 127.0.0.1, not agent-core's host.docker.internal, because git-tools runs on the host. Copilot remains a git-tools-only provider. CLIProxyAPI requires a separately running/authenticated proxy; its client key defaults to the placeholder cliproxyapi, overridden when your proxy requires another key. Its reasoning effort is unset by default.

Zcode requires a GLM Coding Plan key. A general Z.ai API key is not interchangeable, and the general /api/paas/v4 endpoint is not the coding-plan endpoint. Its curated choices are glm-5.3 and glm-5.3-flash, with manual model IDs still accepted. Thinking remains enabled and preserved: effort none/minimal/low maps to low, medium/high to high, and xhigh/max to max; an unset effort leaves the server default (max) in effect. These are the agent-core coding-plan defaults, not a model-availability guarantee.

Saved provider choices are mirrored into per-provider profiles: model, effort, Kimi thinking, OpenRouter pin and custom endpoint (GIT_TOOLS_OPENAI_MODEL_MAIN, GIT_TOOLS_KIMICLI_KIMI_THINKING, OPENAI_BASE_URL, …). This also applies when OpenRouter is selected implicitly by default; API keys are already per provider. Switching reads the target profile into shared settings. This is not a lossless restoration guarantee: resetting to a provider default removes its user-file endpoint key, which can expose a lower-priority custom endpoint on a later switch. Verify destinations after switching; see current limitations.

To configure through environment variables instead:

export GIT_TOOLS_PROVIDER="kimicli"
export KIMICODE_API_KEY="your-key"

Or copy the commented example from your git-tools checkout into the repository where you will run commands (replace the example checkout path):

cp /path/to/git-tools/git-tools.env.example ./git-tools.env

Do not commit real credentials. Ordinary AI commit/issue/PR generation needs a provider; bump, init, and versioning CI do not require an LLM API key.

Files and Precedence

Location Purpose
~/.git-tools/settings.env Saved user-level settings and credentials
~/.git-tools/model-catalog.json Kimi Code's last-known-good catalog, in agent-cli's format, scoped to endpoint and credential fingerprint
./git-tools.env Optional settings in the command's current working directory

For normal settings loading, exported environment variables override env files; settings.env overrides matching values in git-tools.env. CLI options override their corresponding generation defaults. A stale exported variable can therefore hide a newly saved setting.

The application settings readers and credential prechecks use that order, resolving aliases within each source. An exported provider-specific endpoint therefore overrides a saved shared endpoint. Empty exported variables and empty saved credentials are treated as unset. In env files, an explicitly assigned blank for endpoint, model, effort, routing, or thinking controls (including provider profiles) masks lower-priority file values; a bare variable name without = remains unset. A saved blank Qwen endpoint fails required configuration validation. For other compatible providers a blank can resolve to None; client construction rejects that missing endpoint before sending a request. Set a nonblank endpoint rather than relying on transport defaults. See current limitations. The endpoint and credential rows show their application-resolved source without exposing keys; this display does not establish the actual transport destination when the endpoint is absent. An exported endpoint override remains authoritative after an endpoint save. Endpoint lookup itself does not require valid credentials.

API-key replacement exception: explicitly entering a replacement in the API-key editor or completing the provider wizard with a new key also activates that key in the current git-tools process, including subsequent discovery/generation from the interactive menu. This does not change the parent shell's environment; a fresh invocation can use an older exported key again. Unset or update that shell export for a durable change.

When settings.env is absent, legacy ~/.git-tools/config.env or $XDG_CONFIG_HOME/git-tools/config.env (default ~/.config/git-tools/config.env) is migrated automatically. The .git-tools legacy location takes priority. A failed move remains readable as a fallback; legacy files are ignored once settings.env exists.

For a full reset, back up credentials, then remove the saved settings/catalog and any legacy files you no longer want. Unset exported overrides and reconcile any local git-tools.env values too. Otherwise a remaining legacy file may migrate again.

Models and Reasoning

Model catalogs are resolved through git-tools' provider modules and registry. ACRC, OpenAI, Anthropic, Copilot, OpenRouter, and CLIProxyAPI use live discovery and never substitute a shipped model list when discovery fails or yields no selectable entries. Display-name overlays apply only to IDs actually discovered, and the provider default is pinned first only when present. OpenAI applies a local naming/modality heuristic; Anthropic uses its native Models API with its own headers. Kimi Code retains its separate last-known-good cache scoped to endpoint and credential, clearly warned when used after a failed refresh. Qwen and Zcode remain curated and do not probe /models. Large catalogs are searchable. Kimi thinking/effort capabilities come from its catalog entries.

ACRC still requires externally managed VPN/connectivity; an unreachable endpoint produces a diagnostic, not a static replacement list. Qwen requires its actual plan/region endpoint and uses curated choices plus manual entry. Select Model → Enter a model ID manually… to save an exact ID under any provider. Saved/current IDs remain selectable when absent from discovery and are labeled not in catalog. If no current ID or discovered choices exist, the provider's single configured default may be offered with the same qualification; this does not populate the catalog. Listing, saving, or offering an ID does not verify availability or account access. Interactive generation reuses the configured provider and main model after you accept external generation; it does not reopen the model picker or ask for temperature and output-token limits. Use git-tools settings to change saved choices, or --model, --temp, and --max-tokens for invocation-only overrides. Generation reports failed discovery, successful empty discovery, and Kimi cache use, including empty-success diagnostics in direct mode. Canceling the external-generation confirmation stops the operation; it does not accept the default or enter the prompt-copy path.

A successful OpenAI listing filtered to no matching IDs is shown as successful discovery with no selectable models, not replaced by built-ins or misreported as an authentication/network failure. That empty result is memoized for the same endpoint and credential until forced refresh or an identity change. The shared fetcher still classifies a raw response with no usable IDs as malformed; its diagnostic describes that condition. The OpenAI filter remains a naming/modality heuristic, not a chat-completions compatibility check. Verify endpoint support and account access before relying on any model.

git-tools settings model deepseek/deepseek-v4-flash-0731
git-tools settings temperature 1.0
git-tools settings effort xhigh

Main Model

git-tools settings main-model vendor/model

The main model handles all commit/issue/PR generation. model remains an alias for editing main. Resolution in both direct and interactive generation is explicit --model → effective main-model setting → the provider's single default model. That default is configuration, not a replacement discovery catalog. GIT_TOOLS_MODEL_MAIN and legacy GIT_TOOLS_DEFAULT_MODEL are aliases: source precedence wins first, with MODEL_MAIN preferred within the same source. Temperature and maximum output tokens likewise use explicit CLI overrides before their saved global defaults. Provider-specific endpoint, routing, reasoning, and thinking settings are reused without additional configuration questions.

Compatibility: support-model and sub-model (including support_model and sub_model) are removed and treated as unknown settings, not deprecated no-ops. Obsolete GIT_TOOLS_MODEL_SUPPORT, GIT_TOOLS_MODEL_SUB, and GIT_TOOLS_<PROVIDER>_MODEL_SUPPORT keys are ignored. Existing entries are not automatically removed and cannot affect the main model.

Catalogs depend on endpoint and credentials. A failed Kimi Code refresh may use a clearly warned last-known-good cache for that exact identity; changed credentials/endpoints do not reuse another account's cache. Without a suitable cache, explicitly saved/manual IDs and the provider's single default remain available, but no shipped catalog is substituted. Other HTTP client errors bypass the disk cache; authentication/payment/permission errors (401/402/403), server errors, network failures, and malformed responses may use a matching last-known-good catalog, with a warning. Listing or saving an ID does not guarantee your account can access it.

Provider modules live in git_tools/providers/ (originally lifted from agent-cli, with metadata and compatible pure helpers aligned to agent-core) and are wired into the registry in git_tools/settings/mappings.py; there is no mappings.json to maintain.

Endpoint, Routing, and Thinking

git-tools settings api-base https://your-endpoint.example/v1
git-tools settings openrouter-provider any  # Unpinned routing
# Interactive upstream discovery for the selected main model:
git-tools settings openrouter-provider
git-tools settings kimi-thinking enabled   # or disabled, or a tier such as high

OpenRouter upstream choices come from /models/<model>/endpoints; manual slugs are also accepted. A pin uses provider.only and disables fallbacks. Upstream availability is per model, so changing the main model interactively re-asks the pin for the new model; the non-interactive settings main-model <id> keeps a pin the new model's upstream list still contains, clears one it verifiably does not (with a warning), and keeps an unverifiable one with a warning. On OpenRouter, effort none is a real wire value, not clearing the override; other providers handle it as described above. Use effort unset to clear the saved override. Kimi thinking/effort choices respect catalog capabilities where declared, and a direct settings effort <value> is checked against the same Kimi catalog tiers before it is saved. At request time, as in agent-core, explicit kimi-thinking disabled sends thinking.type=disabled and suppresses effort; saving it clears the effort override. Explicit enabled or a real tier alone enables thinking and preserves it with keep: all. With neither an explicit thinking choice nor a tier, no thinking override is sent, regardless of cached catalog modes. Requests use a per-invocation prompt-cache key and the KimiCLI/1.52.0 User-Agent. Kimi treats effort none as no tier, not as a disable-thinking instruction. Qwen always requests preserved thinking; a configured non-none tier is sent for qwen3.8-max*, enables thinking for older Qwen-family models, and is omitted for other manually entered model families.

Provider switching loads remembered choices where present, otherwise provider defaults (no default endpoint for Qwen) and no routing/thinking/effort overrides. General effort prompts preselect saved choices. Kimi's combined thinking picker can instead change a saved tier-only choice when Enter accepts the default; endpoint reset/roundtrip behavior also has a known gap. Neither should be assumed lossless; see current limitations. Noninteractive provider switches do not probe model catalogs. Exported variables still win over saved settings; unset stale exports when switching providers.

Generation Preferences

Settings define stable defaults; modes apply them without re-asking routine configuration. Configure input budgets separately from the maximum output budget:

git-tools settings commit-input-budget 200000
git-tools settings issue-pr-input-budget 200000
git-tools settings max-tokens 32000       # output-budget alias
git-tools settings commit-format          # Scope, body, style, and footer submenu
git-tools settings commit-scope false
git-tools settings commit-body true
git-tools settings commit-body-style prose # bullets (point form) or prose
git-tools settings commit-footer false
git-tools settings issue-pr-source b     # d: diffs, c: messages, b: both

Settings → Commit format groups scope, description/body, description style, and footer, following Commitizen's separation of summary, body, and footer. The short <type>(scope): summary header always remains required; “description (body)” means the optional multiline text below it, not that summary. Defaults preserve the prior format: scope off, body enabled with point-form (bullets) details, footer off. Choose prose for paragraphs without list markers, or turn the body off for a header plus any permitted footer. Style is remembered while the body is off. Completed submenu edits save immediately; Back/Esc leaves the current level, and canceling an individual choice does not save it.

These apply in direct and interactive generation. --token-limit, --scope/--no-scope, --body/--no-body, --body-style bullets|prose, --footer/--no-footer, and --source override them for one run without saving. Both provider and prepared local prompts use the chosen structure. The parser preserves body paragraphs, list continuation indentation, and footer separation rather than converting their style afterward. The prompts instruct the model to include footers only for supported breaking-change facts or supplied issue references, never to invent them; review the generated result. The fixed chore: open release subject ignores these format preferences. Budgets guide diff processing, not the entire request (templates, messages and context are additional input). Task modes, release versions, extra context, and write/send consent are not remembered as preferences.

Input budgets are intentionally general-purpose, best-effort targets based on the shared cl100k_base tokenizer, not exact provider/model token counts. Protected-file retention, minimum per-file quotas, truncation labels, and separators can make the rendered diff exceed the selected target. They are neither strict rendered-diff caps nor model context-window enforcement; choose appropriate headroom for your provider/model and the additional request content.

Environment Reference

Defaults below are application defaults; model/provider capabilities may constrain which request parameters are used. Blank exported variables and credentials are unset; designated assigned file blanks mask lower file values as described in Files and Precedence. A missing effective endpoint now stops client construction; set an explicit nonblank destination and recheck it after provider switches because the profile-reset limitation below remains.

Variable Default / purpose
GIT_TOOLS_PROVIDER openrouter; selects provider
GIT_TOOLS_API_BASE The current provider's endpoint
<PROVIDER>_BASE_URL (e.g. OPENAI_BASE_URL) Per-provider endpoint/profile input; verify after switches and explicit resets
GIT_TOOLS_<PROVIDER>_MODEL_MAIN, …_REASONING_EFFORT, …_KIMI_THINKING, …_OPENROUTER_PROVIDER The provider's remembered profile, written automatically and restored on a switch
GIT_TOOLS_MODEL_MAIN Main-model alias; preferred over the legacy alias within the same source
GIT_TOOLS_DEFAULT_MODEL Legacy alias for the main-model setting
GIT_TOOLS_OPENROUTER_PROVIDER Upstream slug, or any/unset for unpinned routing
GIT_TOOLS_KIMI_THINKING Optional true/false override
GIT_TOOLS_REASONING_EFFORT Provider/model-dependent effort override
GIT_TOOLS_DEFAULT_TEMPERATURE 1.0, range 0–2; existing saved or explicit overrides remain unchanged
GIT_TOOLS_DEFAULT_MAX_TOKENS 32000, positive output budget
GIT_TOOLS_DEFAULT_MAX_RETRIES 1, nonnegative; outer-loop retries after the initial attempt (up to two attempts by default); SDK retries are disabled
GIT_TOOLS_DEFAULT_RETRY_DELAY 1.0 seconds between outer-loop retries, nonnegative; recognized authentication failures stop without retry
GIT_TOOLS_DEFAULT_TOKEN_LIMIT 200000, commit input budget
GIT_TOOLS_DEFAULT_ISSUE_PR_TOKEN_LIMIT 200000, issue/PR input budget
GIT_TOOLS_COMMIT_INCLUDE_SCOPE false, include a Conventional Commit scope by default
GIT_TOOLS_COMMIT_INCLUDE_BODY true, allow the optional multiline description/body below the required summary
GIT_TOOLS_COMMIT_BODY_STYLE bullets; bullets (point form) or prose for the optional body
GIT_TOOLS_COMMIT_INCLUDE_FOOTER false, include a commit footer by default
GIT_TOOLS_ISSUE_PR_SOURCE b, default input source: diffs d, messages c, or both b
GIT_TOOLS_LARGE_DIFF_THRESHOLD 5000
GIT_TOOLS_MIN_FILE_TOKEN_THRESHOLD 1000; small files protected from dropping
GIT_TOOLS_CONSOLE_WIDTH_OFFSET -2, terminal width adjustment
GIT_TOOLS_AZURE_PR_LIMIT auto or false; default auto
GIT_TOOLS_AZURE_PR_MAX_CHARS 4000, range 1–4000 UTF-16 units

PR Length Preferences

git-tools settings pr-limit auto
git-tools settings pr-max-chars 3500

auto detects Azure from origin and applies the result without a routine question; GitHub/unknown origins default to no limit. false disables automatic limiting. There is no saved true mode: use --pr-limit to force it for a command. --no-pr-limit disables it for a command. Legacy azure-pr-limit / azure-pr-max-chars setting aliases are accepted.

Length handling is best-effort, not a hard cap: see CLI usage for retries, UTF-16 counting, and oversized output behavior.

Current limitations

These are confirmed implementation defects, not intended behavior or fixes supplied by this documentation:

  • Default endpoint reset is not durable across sources. Resetting to the official/default URL can remove the remembered user-file endpoint key. A lower-priority provider-specific custom URL can then return on switch-away/back and become active. Do not assume a reset survives switching: inspect the effective endpoint and explicitly set the intended nonblank URL again when needed. Remove or reconcile stale local/env endpoint values deliberately rather than treating the profile as authoritative isolation.
  • Kimi tier-only picker default is not a no-op. With thinking unset and valid effort high, generation can use enabled/high, while the combined picker selects the catalog's default low or off. Enter can persist that different choice. Explicitly choose the intended tier, or set it directly with git-tools settings kimi-thinking high when that tier is supported; recheck saved values afterward. Catalog restrictions apply in the picker; explicit off controls request construction.

Additional defensive gaps: malformed Kimi cache metadata can raise an exception instead of falling back, and catalog HTTP diagnostics can include server-supplied error text. Treat logs as potentially sensitive; a reflected credential in an upstream error could appear in that text. Review/redact logs before sharing. These are conditional robustness risks, not evidence that a real service reflected a key.

Client construction now rejects missing endpoints before SDK creation; this prevents the previous unrelated-host fallback but does not repair the profile-reset limitation above. Do not treat passing unit tests, an endpoint menu row, or a successful model listing as proof that every subsequent destination/profile transition is correct.

Repository Version Configuration

Provider settings are separate from version configuration. .cz.toml is the sole version/tag authority; Python, Node, and supported Cargo manifests/lockfiles are best-effort sync consumers. See versioning for fields, examples, monorepos, and failure behavior.