Configuration examples
Example configuration files shipped in examples/mat/.
examples/mat/backends.json
Section titled “examples/mat/backends.json”{ "backends": [ { "nickname": "ccw", "config_dir": "claudew", "auth_var": "CLAUDE_CODE_OAUTH_TOKEN_CCW", "prompt_file": "CLAUDE.md", "kind": "claude" }, { "_comment": "default_model / default_effort are optional raw pass-through strings applied at launch. claude-kind: --model + --effort (the starting level can be changed in-session with /effort). codex: --model + --config model_reasoning_effort=<effort>. copilot: --model + --effort. Omit or empty-string default_model to add no model flag; omit or empty-string default_effort and the shared resolver falls back to high (pi and freebuff are the documented exceptions — neither launch argv carries an effort flag, and on freebuff the effort a turn runs at is server-owned). kind: freebuff also ignores default_model — its argv carries no model flag. No mat-side validation — the native CLI validates model/effort values. context_window_size caps the auto-compaction window: plain integer (250000) or k/m shorthand (350k, 1m). claude-kind exports CLAUDE_CODE_AUTO_COMPACT_WINDOW; codex adds --config model_auto_compact_token_limit. Omit to use the CLI's per-model default (200k standard / 1M extended). kind: copilot, kind: pi and kind: freebuff accept the field but no launch path reads it.", "nickname": "cch", "config_dir": "claudeh", "auth_var": "CLAUDE_CODE_OAUTH_TOKEN_CCH", "prompt_file": "CLAUDE.md", "kind": "claude", "default_model": "opus", "default_effort": "high", "context_window_size": "350k" }, { "_comment": "Example: selector-only gateway backend. auth_var is omitted (null) so this backend requires MAT_ANTHROPIC_GATEWAY. gateway_selector 'auto' routes through AQG's pooled failover. Allowed charset: [A-Za-z0-9_-].", "nickname": "ccauto", "config_dir": "claudeauto", "prompt_file": "CLAUDE.md", "kind": "claude", "gateway_selector": "auto" }, { "nickname": "ccz", "config_dir": "claudez", "auth_var": "Z_AI_API_KEY", "prompt_file": "CLAUDE.md", "kind": "claude", "base_url_var": "Z_AI_CLAUDE_BASE_URL" }, { "nickname": "ccd", "config_dir": "clauded", "auth_var": "DEEPSEEK_API_KEY", "prompt_file": "CLAUDE.md", "kind": "claude", "base_url_var": "DEEPSEEK_CLAUDE_BASE_URL" }, { "_comment": "Example: an enterprise/team Codex subscription through the same custom Responses provider path used by BYOK. auth_var names the opaque bearer key source; base_url is the configured OpenAI-compatible endpoint. mat exports the key only as MAT_CODEX_API_KEY and writes the provider into the real role-local CODEX_HOME/config.toml.", "nickname": "codex", "config_dir": "codex", "auth_var": "CODEX_ACCESS_TOKEN_SEATA", "base_url": "https://chatgpt.com/backend-api/codex", "prompt_file": "AGENTS.md", "kind": "codex", "model_provider": "codex-team", "default_model": "gpt-5.6-luna", "default_effort": "high", "wire_api": "responses" }, { "_comment": "Example: a third-party Codex provider. base_url_var is resolved from the current environment or ~/.bashrc.secret; model_catalog_json is copied as a real role-local models.json after JSON validation. Do not put an API key in config.toml.", "nickname": "deepseek", "config_dir": "deepseek", "auth_var": "DEEPSEEK_API_KEY", "base_url_var": "DEEPSEEK_BASE_URL", "prompt_file": "AGENTS.md", "kind": "codex", "model_provider": "deepseek", "wire_api": "responses", "default_model": "deepseek-v4-flash", "default_effort": "high", "model_catalog_json": "~/.codex/models.json" }, { "_comment": "Personal subscriptions that expose no provider key and endpoint stay on legacy credential sharing. This path may symlink auth.json/config.toml from the backend's bare canonical home; it is not an implicit fallback for an explicit provider.", "nickname": "codex-personal", "config_dir": "codex-personal", "prompt_file": "AGENTS.md", "kind": "codex", "default_effort": "high" }, { "_comment": "Example: Codex via the gateway route. gateway_selector is authoritative — auth_var / base_url / model_provider / wire_api / model_catalog_json are ignored on this entry. mat writes the fixed provider identity `mat-codex-gateway` into a real role-local config.toml and exports MAT_CODEX_API_KEY=<gateway_selector>. The origin is MAT_CODEX_GATEWAY (e.g. `export MAT_CODEX_GATEWAY=http://gateway.local:8080`), falling back to MAT_ANTHROPIC_GATEWAY; with both unset or empty the launch fails before Codex starts.", "nickname": "codex-gateway", "config_dir": "codex-gateway", "prompt_file": "AGENTS.md", "kind": "codex", "gateway_selector": "chn" }, { "_comment": "Example: Codex on the official auth-only route. No endpoint declared — mat resolves the entry to https://chatgpt.com/backend-api/codex with provider identity `codex-team`. auth_var resolves from the current environment or ~/.bashrc.secret; nothing else is consulted.", "nickname": "codex-official", "config_dir": "codex-official", "auth_var": "CODEX_OFFICIAL_KEY", "prompt_file": "AGENTS.md", "kind": "codex" }, { "_comment": "INVALID example (do NOT enable): provider metadata (model_provider) without an endpoint (base_url / base_url_var). The classifier returns `invalid-direct` and the launcher fails closed before Codex starts. Fix by adding an endpoint, or strip the metadata fields so the entry resolves to a valid route.", "_comment_disabled": "codex-bad", "_comment_config_dir": "codex-bad", "_comment_auth_var": "CODEX_BAD_KEY", "_comment_prompt_file": "AGENTS.md", "_comment_kind": "codex", "_comment_model_provider": "custom" }, { "_comment": "Example: Copilot BYOK. auth_var/base_url_var/default_model/default_effort stay the existing launch contract; copilot_provider_type is the new protocol discriminator. Omit copilot_provider_type and mat defaults Copilot BYOK to anthropic.", "nickname": "copiloto", "config_dir": "copiloto", "auth_var": "OPENAI_API_KEY", "prompt_file": "copilot-instructions.md", "kind": "copilot", "base_url_var": "OPENAI_BASE_URL", "copilot_provider_type": "openai", "default_model": "gpt-5", "default_effort": "high" }, { "nickname": "copilot", "config_dir": "copilot", "prompt_file": "copilot-instructions.md", "kind": "copilot", "default_model": "gpt-5", "default_effort": "high" }, { "_comment": "Example: Copilot native login with its own GitHub token variable. No base_url_var/gateway_selector/copilot_provider_type, so this stays a native-login backend (not BYOK); auth_var here resolves as COPILOT_GITHUB_TOKEN and takes precedence over the global MAT_COPILOT_GITHUB_TOKEN, letting this backend log in as a distinct GitHub identity. Must be a fine-grained PAT (github_pat_...) or `gh auth token` output (gho_...) -- a classic ghp_... PAT fails the launch.", "nickname": "copilotgh", "config_dir": "copilotgh", "auth_var": "MAT_COPILOT_GITHUB_TOKEN_GH", "prompt_file": "copilot-instructions.md", "kind": "copilot", "default_model": "gpt-5", "default_effort": "high" }, { "_comment": "Example: OpenCode Zen. The role home owns all XDG roots and mat renders the global role prompt at config/opencode/AGENTS.md; auth_var is required because isolated homes do not inherit OpenCode's personal auth file. context_window_size caps the model's effective window via a provider model-limit override written to the role-isolated opencode.json under the default_model's <provider-id>/<model-id> pair (e.g. opencode/... or opencode-go/...).", "nickname": "opencode", "config_dir": "opencode", "auth_var": "OPENCODE_API_KEY", "prompt_file": "config/opencode/AGENTS.md", "kind": "opencode", "default_model": "opencode/deepseek-v4-flash-free", "default_effort": "high", "context_window_size": "256k" }, { "_comment": "Example: OpenCode BYOK through an OpenAI-compatible endpoint. Use an opencode/<model> default_model so it selects the provider config mat writes in the isolated role home.", "nickname": "opencode-byok", "config_dir": "opencode-byok", "auth_var": "OPENAI_API_KEY", "prompt_file": "config/opencode/AGENTS.md", "kind": "opencode", "base_url_var": "OPENAI_BASE_URL", "default_model": "opencode/my-model", "default_effort": "high" }, { "_comment": "Example: pi via the gateway route. gateway_selector is authoritative — auth_var / base_url / base_url_var / model_provider are ignored on this entry. mat writes a real role-local models.json (baseUrl = MAT_PI_GATEWAY, falling back to MAT_ANTHROPIC_GATEWAY) and exports MAT_PI_API_KEY=<gateway_selector>. default_model is required: a bare model id (recommended) renders provider `mat` and launches as `--model mat/<model-id>`; a `<prefix>/<model-id>` renders provider `<prefix>`. wire_api is optional here and defaults to anthropic; set openai, responses, or google for a non-Anthropic pool member.", "nickname": "pi-gateway", "config_dir": "pi-gateway", "gateway_selector": "chn", "default_model": "claude-sonnet-4-5", "prompt_file": "SYSTEM.md", "kind": "pi" }, { "_comment": "Example: Command Code (cmd). HOME is cmd's native home variable, so per-role isolation rides the launcher's HOME rebind; credentials symlink the role-home .commandcode/auth.json to the canonical ~/.commandcode/auth.json so one `cmd login` serves every role. nested prompt_file renders the role constitution at .commandcode/AGENTS.md, where cmd's user-memory load finds it. default_model / default_effort / context_window_size are inert on this kind — cmd's argv carries no model or effort flag, and no launch path reads context_window_size. tier still gates explore/audit. Authenticate later with `cmd login`.", "nickname": "commandcode", "config_dir": "commandcode", "prompt_file": ".commandcode/AGENTS.md", "kind": "commandcode", "tier": "strong" } ]}examples/mat/user.conf
Section titled “examples/mat/user.conf”# Optional mat user config.## DEPRECATED: git config is now the canonical store for these settings. Prefer:## git config --global mat.username "your name"# git config --global mat.defaultBackend claude## git config resolves system -> global -> local, so a per-repo override works# without any extra mat handling. Already have a user.conf? Migrate it with:## mat config migrate # dry-run, shows what would be written# mat config migrate --confirm## This file is still read as a lower-priority fallback this release (git config# wins per key); a follow-up release removes user.conf loading entirely.## Copy to ~/.config/mat/user.conf and edit to taste.
export MAT_USER_NAME="your name"export MAT_DEFAULT_BACKEND="claude"
# Note: MAT_NOTIFY is NOT read from this file. To suppress the session-start# Telegram notification, export MAT_NOTIFY=0 in the shell that invokes mat# (e.g. .bashrc/.zshrc), or inline for a single launch.