Configuration

Hamr uses a layered config system with clear precedence.

Config Files

Level	Path	Purpose
Defaults	Built-in	Safe fallback values
Global TOML	~/.config/hamr/config.toml	Machine-wide settings
Local TOML	<repo>/.hamr.toml	Per-project overrides
Models JSON	~/.hamr/agent/models.json	Custom providers & models

Precedence

defaults → global TOML → local TOML

Local TOML always wins over global. models.json defines provider/model registrations independently — it doesn't compete with TOML for the same keys.

Quick Start

Configure a local or cloud provider

From the TUI: /login → pick a method:

• Use a subscription — OAuth login for Anthropic, GitHub Copilot, etc.
• Use an API key — enter a key for any built-in cloud provider
• Use a custom/self-hosted endpoint — configure a local server (LM Studio, llama.cpp, Ollama, vLLM) or any OpenAI/Anthropic-compatible proxy. Auto-discovers models. Saves to ~/.hamr/agent/models.json.

Manual config files

# Global TOML settings
vim ~/.config/hamr/config.toml

# Project-local overrides
vim .hamr.toml

# Custom providers and models
vim ~/.hamr/agent/models.json

hamr config (without a subcommand) opens the TUI package manager for installing extensions and skills, not for editing provider config.

Config Format (TOML)

Active Provider and Model

[active]
provider = "relay"
model = "Qwen3.6-35B-A3B-UD-IQ3_XXS.gguf"
thinking = "off"

Provider Definitions

[providers.relay]
enabled = true
name = "Relay"
compatibility = "openai-compatible"
base_url = "http://127.0.0.1:1234/v1"

[[providers.relay.models]]
id = "Qwen3.6-35B-A3B-UD-IQ3_XXS.gguf"
display_name = "Qwen3.6 35B Local"
context_window = 131072
supports_thinking = false

[providers.deepseek]
enabled = true
name = "DeepSeek"
compatibility = "openai-compatible"
base_url = "https://api.deepseek.com/v1"
api_key_env = "DEEPSEEK_API_KEY"

[[providers.deepseek.models]]
id = "deepseek-chat"
display_name = "DeepSeek V3"
context_window = 128000
supports_thinking = false

Custom Headers

[providers.relay.headers]
"X-Custom-Header" = "${MY_ENV_VAR}"

Skills

Skill entries are filesystem paths. Use ~/... for home-relative paths, ./... for project-relative, or absolute paths.

[skills]
enabled = ["~/.agents/skills/coderabbit-review"]
disabled = ["~/.agents/skills/grill-me"]

MCP Servers

[mcp.servers.context7]
enabled = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

TUI

[tui]
mouse = false
alternate_screen = true
cmux_mode = false

Set cmux_mode = true to reduce sexy-tui-rs frame rate and retained live cards when running many parallel TUI sessions.

AI Core Visual Profile

coreVisualProfile = "model"

Use model to choose the AI core morphology from the active model ID. You can also force one profile:

coreVisualProfile = "qwen"

Canonical values are lowercase: model, default, qwen, openai, claude, deepseek, and gemini. Hamr also accepts core_visual_profile and legacy [provider]-scoped placement for compatibility.

Legacy Format (backward compatible)

The single-provider format from v0.1-v0.3 is still supported:

[provider]
kind = "openai-compatible"
base_url = "http://127.0.0.1:1234/v1"
model = "Qwen3.6-35B-A3B-UD-IQ3_XXS.gguf"
api_key = "sk-no-key-required"

When both formats exist, the multi-provider format takes precedence for provider definitions. The legacy provider.model is used as a fallback for active.model.

Environment Variables

Variable	Purpose
HAMR_CONTEXT_BUDGET_TOKENS	Override context budget
HAMR_MAX_TOOL_CALLS	Override max tool calls
HAMR_LOG_LEVEL	Log level: trace, debug, info, warn, error
DEEPSEEK_API_KEY	DeepSeek API key
OPENAI_API_KEY	OpenAI API key
ANTHROPIC_API_KEY	Anthropic API key

Validation

Invalid config is NOT silently ignored. Parse errors produce clear messages:

[hamr] Config error:
providers.my-provider: base_url is required
active.thinking: must be one of: off, low, medium, high, xhigh, auto

Setting Config from the TUI

Press / in the TUI and type settings to open the settings menu. Use the Model tab to change provider, model, and thinking levels. Use the Providers tab to view configured providers. Changes persist to the local .hamr.toml if one exists, otherwise to the global config.

Agent Mandate

Inject a behavioral mandate into the system prompt once at conversation start. This is the most token-efficient way to steer agent behavior — it is prepended once, never repeated.

[agent]
mandate = "Use short sentences. Big sentence bad. Be concise."

The mandate is inserted before the standard Hamr system prompt. Use it for:

• Enforcing output style (short sentences, no markdown, etc.)
• Role-specific guardrails ("never delete files without asking")
• Model-specific steering (helpful for local models that need extra guidance)

Context Strategy

Control how aggressively Hamr compacts conversation context:

[agent]
context_strategy = "moderate"

Supported strategies: aggressive, moderate, light, none, or off.

Override per-run from the CLI:

hamr run --task "..." --strategy aggressive