Settings
Persistent configuration is split so install upgrades stay safe and permission rules stay lean:
| Path | Holds |
|---|---|
~/.hipmmcode/config.json | Models, API keys, MCP, UI, provider presets (0600 — can hold secrets) |
~/.hipmmcode/settings.json | Claude-compatible permissions (defaultMode, allow/deny/ask), hooks, and related policy (preferred for rules) |
Project .hipmmcode/settings.json / .settings.local.json | Project / local overrides |
You rarely edit by hand:
hipmmcode config show # full config, secrets redacted
hipmmcode config set KEY=VALUE # set any key
hipmmcode config providers # list built-in channel presetsInside the REPL, /config key=value (alias /settings) does the same live.
First-run seeds (v0.14.1+)
If ~/.hipmmcode/settings.json is missing, hipmmcode creates a minimal file:
{
"permissions": {
"defaultMode": "auto"
}
}If the release includes default-skills/, the L1 pack is synced into ~/.hipmmcode/skills/ on first launch (or via hipmmcode skill install-defaults). See Skills and Permissions.
Updating the binary keeps these user files. It does not reset keys, and does not re-download historical allow-list junk into config.json.
Core keys
| Key | Default | Description |
|---|---|---|
defaultProvider | openai | Default channel id |
defaultModel | gpt-4o-mini | Default model id |
<provider>.apiKey | — | API key per channel (anthropic.apiKey=sk-ant-...) |
<provider>.models | dynamic | Comma-separated model whitelist for a channel |
<provider>.modelOverride.<model>.contextWindow | — | Override a model's context window (tokens) |
<provider>.modelOverride.<model>.maxOutputTokens | — | Override a model's max output |
fallbackModel / fallbackModels | — | Up to 3 models tried in order when the primary is overloaded |
apiKeyHelper | — | Shell command that prints an API key (for vaults / short-lived creds) |
effort (reasoningEffort) | provider default | Reasoning effort: deepseek-anthropic defaults to max; Codex-backed channels default to high; other channels default to off |
language | — | Preferred response language (free-form) |
activeLegion | — | Legion active by default (see Agent teams) |
UI & terminal
| Key | Default | Description |
|---|---|---|
tui | fullscreen | Startup renderer: fullscreen or inline |
hudStyle | native | Bottom HUD: native / compact / force-native |
colorTheme | default | Color theme (see /color) |
editorMode | normal | Input editing: normal (emacs) or vim |
defaultShell | host default | Shell for ! bang commands: bash / powershell |
statusLineCommand | — | External status-line command (replaces built-in HUD) |
statusLinePadding | — | Padding for the external status line |
subagentStatusLineCommand | — | Per-teammate status line |
timestamps | false | Per-message timestamps in the transcript |
tips | true | Rotating shortcut hints under the input |
terminalTitle | true | Session status in the terminal tab title |
terminalTitleFromRename | true | Use the /rename name in the title |
terminalProgress | true | Terminal progress indicator during turns |
notifyOnDone | false | Notify when a turn finishes unfocused |
notifyOnInputNeeded | false | Notify when a permission prompt opens unfocused |
notifyChannel | auto | auto / iterm2 / iterm2_with_bell / terminal_bell / kitty / ghostty / off |
awayRecap | true | "Welcome back" summary after ≥5 min idle |
teamMatePreview | true | Persistent teammate preview row |
verbose | false | Verbose output |
showWarnings | false | Show WARN-level log lines |
outputStyle | — | Active response output style |
diffTool | — | External tool for /diff (vscode, meld, vimdiff, …) |
userAliases | {} | Personal slash-command aliases (managed by /alias) |
Behavior & safety
| Key | Default | Description |
|---|---|---|
bashPromptForWrites | true | Confirm state-changing shell commands |
confirmOutsideWorkspace | true | Confirm file access outside cwd / added dirs |
permissions | {} | Allow/deny/ask rules (prefer settings.json for defaultMode) — see Permissions |
hooks | {} | Lifecycle hooks — see Hooks |
sandbox.* | off | OS-level bash sandbox — see Permissions |
autoMode | — | Autonomous-mode rules { allow, hard_deny, classifierModel } |
trustedDirs | [] | Directories you've accepted the trust dialog for |
worktreeBaseRef | head | Worktree base: head or fresh (origin default branch) |
Memory & context
| Key | Default | Description |
|---|---|---|
autoMemoryEnabled | true | Master gate for persistent memory (read + write) |
autoMemoryOnExit | true | Extract memories at /exit |
autoMemoryOnExec | false | Extract memories after headless runs |
autoMemoryOnEveryTurn | false | Extract after every turn (token-hungry) |
memoryRelevanceSelector | false | LLM-based memory file selection |
autoCompactEnabled | true | Auto-compaction near the context ceiling |
autoCompactWindow | — | Force compaction earlier (token cap). v0.11.0+: Also configurable via native HIPMMCODE_AUTO_COMPACT_WINDOW; legacy CLAUDE_CODE_AUTO_COMPACT_WINDOW is an absent-only fallback (clamped to 100k–1M, applied as min(override, model_context)) |
apiMicrocompactEnabled | true | Evict stale tool results before full compaction. v0.11.0+: Preserves tool_result blocks with image/document attachments |
instructionExcludes | [] | Glob patterns excluded from instruction loading |
Agents & orchestration
| Key | Default | Description |
|---|---|---|
teamMateDefaultModel | — | Model for spawned teammates (leader = inherit) |
advisorModel | — | Second-opinion model for the Advisor tool |
advisor | false | Proactively consult the advisor before major work |
autoJudge | false | Auto-judge teammate results |
goalEvaluatorModel | — | Cheap model that verifies /goal conditions |
goalMaxContinuations | 25 | Max auto-continuations for /goal |
Search
| Key | Default | Description |
|---|---|---|
anysearchApiKey | — | AnySearch key — enables WebSearch on channels without native search |
anysearchEnabled | auto | AnySearch on/off (auto-on when a key is set) |
nativeSearchEnabled | true | Allow provider-native search; off forces AnySearch everywhere |
See Web search.
MCP
| Key | Default | Description |
|---|---|---|
mcpServers | {} | User-scope MCP servers |
projectMcpServers | {} | Local-scope servers (per project) |
projectMcpApprovals | {} | Trust decisions for project .mcp.json servers |
mcpDisabled | [] | Servers disabled via /mcp disable |
mcpSyncFromClaude | true | Auto-import externally configured MCP servers |
See MCP servers.
Compatibility
| Key | Default | Description |
|---|---|---|
claudeCodeCompat | false | Adopt the .claude ecosystem: ~/.claude/settings.json layers (user → project → local → managed), ~/.claude/skills, .claude/agents, MCP server import, CLAUDE.md instructions |
With compat on, settings merge in layers (low → high): hipmmcode config → user settings → project settings → local settings → managed/policy settings → CLI flags. --settings <file|json> injects one more layer from the command line; --setting-sources user,project,local restricts which layers load.
CLAUDE_CONFIG_DIR still selects the independent Claude compatibility tree used for importing CLAUDE.md, .claude-plugin/, Claude hooks/MCP, and other read-only Claude assets (default ~/.claude).
From v0.16.0, when HIPMMCODE_CONFIG_DIR is unset, CLAUDE_CONFIG_DIR is also accepted as a fallback for HiPMMCode's native root — so Claude-Code-compatible / Grok launches that only set CLAUDE_CONFIG_DIR land state in one place. If both are set, native writes stay under HIPMMCODE_CONFIG_DIR and Claude-compat reads still use CLAUDE_CONFIG_DIR.
Environment variables
The native configuration root is resolved as:
HIPMMCODE_CONFIG_DIR → else CLAUDE_CONFIG_DIR (v0.16.0+) → else HIPMMCODE_HOME → else ~/.hipmmcode.
Use HIPMMCODE_* for HiPMMCode-owned controls. Where a legacy CLAUDE_* / CLAUDE_CODE_* spelling is listed, it is consulted only when the native variable is absent (except CLAUDE_CONFIG_DIR, which is an intentional native-root fallback when HIPMMCODE_CONFIG_DIR is unset). A present native value (including false, 0, empty, or malformed) is authoritative and cannot expose a conflicting legacy value.
| Variable | Description |
|---|---|
HIPMMCODE_DEFAULT_PROVIDER / HIPMMCODE_DEFAULT_MODEL | Override the default provider/model without editing config.json — always wins over the on-disk default |
ANTHROPIC_MODEL | Compat shim: same as HIPMMCODE_DEFAULT_MODEL, but only applied when the resolved default provider is Anthropic-protocol (so it can't hijack an unrelated OpenAI-compat default). HIPMMCODE_DEFAULT_MODEL wins if both are set |
ANTHROPIC_BASE_URL | Compat shim: overrides the native anthropic channel only (for example, a relay). It never overrides deepseek-anthropic, qwen-anthropic, or qwen-token-plan-anthropic. An explicit custom.<id>.baseUrl in config.json still wins |
ANTHROPIC_AUTH_TOKEN | Compat shim: bearer-token alias for the native anthropic channel only — tried after ANTHROPIC_API_KEY if both are set |
OPENAI_API_KEY ANTHROPIC_API_KEY GEMINI_API_KEY DEEPSEEK_API_KEY KIMI_API_KEY | Provider keys (fallback when no stored key) |
QWENCLOUD_TOKEN_PLAN_API_KEY / QWEN_TOKEN_PLAN_API_KEY | Dedicated sk-sp-... credential for qwen-token-plan / qwen-token-plan-anthropic; prefer Alibaba's official QWENCLOUD_TOKEN_PLAN_API_KEY, while the latter is a HiPMMCode compatibility alias; never falls back to pay-as-you-go credentials |
DASHSCOPE_API_KEY / QWEN_API_KEY | Pay-as-you-go credential for qwen / qwen-anthropic; QWEN_API_KEY is the legacy alias. Use sk-... or sk-ws-..., never a Token Plan sk-sp-... key |
<CUSTOM_ID>_API_KEY | Key for a custom channel (uppercased id) |
GOOGLE_API_KEY GH_TOKEN GITHUB_TOKEN GLM_API_KEY … | Conventional per-channel fallbacks — catalog channels also accept the alternate env-var names their upstream ecosystems use (see Model channels) |
AWS_BEARER_TOKEN_BEDROCK | Bearer-token auth for the bedrock channel |
HIPMMCODE_PTY_PER_AGENT / _PER_THREAD / _PER_WORKSPACE / _PER_TENANT / HIPMMCODE_MAX_PTY_SESSIONS | Quota limits for exec_command interactive terminal sessions (defaults 2/4/8/16/64) |
HIPMMCODE_TENANT_ID / HIPMMCODE_WORKSPACE_ROOT | hipmmcode serve multi-tenant identity / workspace cwd containment — see Server |
ANYSEARCH_API_KEY / ANYSEARCH_KEY | AnySearch key |
HIPMMCODE_CONFIG_DIR | Highest-priority override for the native configuration/state root |
CLAUDE_CONFIG_DIR | Claude compatibility tree (always). v0.16.0+: also selects the native root when HIPMMCODE_CONFIG_DIR is unset |
HIPMMCODE_HOME | Supported whole-tree root override, used when neither HIPMMCODE_CONFIG_DIR nor CLAUDE_CONFIG_DIR is set |
HIPMMCODE_TEAMS_ROOT | Override just the teams directory |
HIPMMCODE_VIDEO_MAX_MB | Inline video size cap (default 32) |
HIPMMCODE_SANDBOX (+ _NETWORK, _WRITABLE, _HIDE, _FAIL) | OS sandbox switches — see Permissions |
HIPMMCODE_DISABLE_MICROCOMPACT | Disable micro-compaction |
HIPMMCODE_EXPERIMENTAL_FLAG / HIPMMCODE_EXPERIMENTAL_<NAME> | Experimental flags master switch / per-flag gate (hipmmcode flags) |
VISUAL / EDITOR | Editor for /editor and /memory |
RUST_LOG | Tracing filter (debug logging) |
Native-first Claude compatibility aliases
Every row uses the same absent-only rule described above.
| Native variable | Legacy fallback | Purpose |
|---|---|---|
HIPMMCODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD | CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD | Load compatible instructions from --add-dir directories |
HIPMMCODE_AGENT_SDK_DISABLE_BUILTIN_AGENTS | CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS | Disable bundled agent profiles |
HIPMMCODE_API_KEY_HELPER_TTL_MS | CLAUDE_CODE_API_KEY_HELPER_TTL_MS | API-key helper cache lifetime |
HIPMMCODE_AUTO_COMPACT_WINDOW | CLAUDE_CODE_AUTO_COMPACT_WINDOW | Auto-compaction context window (100k–1M) |
HIPMMCODE_AUTOCOMPACT_PCT_OVERRIDE | CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | Auto-compaction percentage override |
HIPMMCODE_DISABLE_1M_CONTEXT | CLAUDE_CODE_DISABLE_1M_CONTEXT | Disable the 1M context tier |
HIPMMCODE_DISABLE_AUTO_MEMORY | CLAUDE_CODE_DISABLE_AUTO_MEMORY | Disable automatic persistent memory |
HIPMMCODE_DISABLE_BACKGROUND_TASKS | CLAUDE_CODE_DISABLE_BACKGROUND_TASKS | Disable background tasks |
HIPMMCODE_DISABLE_THINKING | CLAUDE_CODE_DISABLE_THINKING | Disable reasoning-effort escalation |
HIPMMCODE_EFFORT_LEVEL | CLAUDE_CODE_EFFORT_LEVEL | Set the model effort level |
HIPMMCODE_FILE_READ_MAX_OUTPUT_TOKENS | CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS | Bound selected Read output |
HIPMMCODE_IDE_HOST_OVERRIDE | CLAUDE_CODE_IDE_HOST_OVERRIDE | Override the IDE MCP bridge host |
HIPMMCODE_MAX_OUTPUT_TOKENS | CLAUDE_CODE_MAX_OUTPUT_TOKENS | Bound headless output |
HIPMMCODE_MAX_SUBAGENTS_PER_SESSION | CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION | Session Agent quota |
HIPMMCODE_MAX_TOOL_USE_CONCURRENCY | CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY | Parallel tool-call limit |
HIPMMCODE_MAX_WEB_SEARCHES_PER_SESSION | CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION | Session WebSearch quota |
HIPMMCODE_MCP_TOOL_IDLE_TIMEOUT | CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT | Remote MCP idle timeout |
HIPMMCODE_PROCESS_WRAPPER | CLAUDE_CODE_PROCESS_WRAPPER | Validated daemon self-spawn wrapper |
HIPMMCODE_SAFE_MODE | CLAUDE_CODE_SAFE_MODE | Disable customizations for troubleshooting |
HIPMMCODE_SIMPLE | CLAUDE_CODE_SIMPLE | Skip instruction/MCP/hook/plugin discovery |
HIPMMCODE_SSE_PORT | CLAUDE_CODE_SSE_PORT | Force the IDE bridge port |
HIPMMCODE_SUBAGENT_MODEL | CLAUDE_CODE_SUBAGENT_MODEL | Override the Agent model |
Child-process protocol variables
Protocol interoperability is intentionally dual-name rather than fallback-only. HiPMMCode exports native fields such as HIPMMCODE_SESSION_ID, HIPMMCODE_EFFORT, HIPMMCODE_PROJECT_DIR, HIPMMCODE_PLUGIN_ROOT, and HIPMMCODE_PLUGIN_DATA; compatible hooks/plugins/helpers may also receive their CLAUDE_* counterparts. Skills expand both ${HIPMMCODE_*} and the corresponding ${CLAUDE_*} placeholders to the same native-resolved values.
File map
<native-config-root>/
├── config.json # everything above
├── sessions/ # one JSON per session
├── projects/<key>/memory/ # persistent memory per project
├── agents/ # your agent profiles (*.md)
├── skills/ # installed skills
├── legions/<name>/ # legion bundles (agents + skills)
├── teams/<name>/ # team state: config, inboxes, tasks
├── plugins/ # installed plugins
└── direct-connect.json # serve discovery lockfile<native-config-root> means HIPMMCODE_CONFIG_DIR, else CLAUDE_CONFIG_DIR (v0.16.0+), else HIPMMCODE_HOME, else ~/.hipmmcode.
Project-level files HiPMMCode reads natively include .mcp.json, HIPMMCODE.md, .hipmmcode/commands/, .hipmmcode/agents/, .hipmmcode/rules/, and .hipmmcode/scheduled_tasks.json. Compatibility inputs include AGENTS.md, CLAUDE.md, .claude/commands/, .claude/agents/, .claude/rules/, and a legacy .claude/scheduled_tasks.json only when the native cron file is absent. External plugin manifests keep the .claude-plugin/ protocol name.