Troubleshooting

First stop: doctor

hipmmcode doctor          # keys, config path, home dir, MCP/skills counts, common problems
hipmmcode doctor --json   # machine-readable

In the REPL, /doctor runs the same check.

Common issues

"No API key" / model errors on the first turn

• hipmmcode doctor shows key presence per channel. Set one: hipmmcode config set <provider>.apiKey=… or the matching env var.
• OAuth channels (openai-codex, xai-oauth, qwen-oauth): run hipmmcode model <channel> and complete device-code login (or ensure the external CLI file exists: ~/.codex/auth.json, ~/.grok/auth.json, ~/.qwen/oauth_creds.json).
• If a proxy channel rejects a model name, check /model — the picker only lists what the channel actually serves. hipmmcode models -p <channel> shows the live list.
• DeepSeek: use API ids deepseek-v4-flash / deepseek-v4-pro (not marketing date tags). Prefer channel deepseek-anthropic for native search.

WebSearch says search is disabled / needs a key

• On Anthropic / deepseek-anthropic / Gemini / xai / xai-oauth, search is channel-native — ensure nativeSearchEnabled is on (/nativesearch on).
• On other channels, set AnySearch: /anysearch key=as_sk_… then /anysearch on. See Web search.

GenerateImage fails on Grok with HTTP 400

xAI Imagine rejects OpenAI-only body fields. hipmmcode maps size/quality for you; if you call the API yourself, use Imagine parameters (aspect_ratio, response_format: b64_json). Use channel xai or xai-oauth.

A custom proxy replies with errors or empty responses

Test the endpoint directly before blaming configuration:

curl -sS -X POST "$BASE_URL/v1/messages" -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"model":"…","max_tokens":32,"messages":[{"role":"user","content":"hi"}]}' -v

Empty replies, connection drops at a fixed interval (~3 s), or intermittent 5xx storms are proxy-side (upstream timeout, missing SSE buffering config) — raise the proxy's timeouts and disable response buffering for streaming.

The TUI looks corrupted / colors are wrong

• Use a modern terminal (on Windows: Windows Terminal, not the legacy console).
• hipmmcode config set tui=inline switches to the classic renderer.
• /color picks a theme that fits your palette; NO_COLOR and dumb-terminal fallbacks are respected in headless output.

Shift+Enter inserts nothing / sends the message

Run /terminal-setup once — it installs the right key mapping for your terminal (Option+Enter on Apple Terminal).

Default skills pack missing after install

hipmmcode skill install-defaults
hipmmcode skills

If the CLI cannot find the pack: keep default-skills/ next to the binary (release tarball layout), or set HIPMMCODE_DEFAULT_SKILLS_DIR to that directory. See Skills — default pack.

Too many permission prompts / huge allow lists

New installs use defaultMode: auto. Prefer Auto over pasting long permissions.allow dumps into config.json. Rules belong in ~/.hipmmcode/settings.json. Reset to lean defaults:

{
  "permissions": {
    "defaultMode": "auto"
  }
}

A skill / hook / MCP server is misbehaving

hipmmcode --safe-mode      # run with ALL customizations disabled
hipmmcode --bare           # fast start: skip discovery entirely

If safe mode fixes it, re-enable pieces one at a time (/reload-skills, /mcp, /hooks).

Session feels slow near the context limit

Watch the HUD gauge. /compact reclaims most of the window; micro-compaction and auto-compact are on by default. /context shows exactly what's consuming tokens.

Permission prompts in an unattended run

Headless ask decisions fail closed. Pick a strategy: --permission-mode acceptEdits, --permission-webhook, or (trusted sandboxes only) --dangerously-skip-permissions. See Permissions.

Debug logging

RUST_LOG=hipmmcode=debug hipmmcode …      # tracing output
hipmmcode config set showWarnings=true    # WARN lines in the REPL (or /warnings on)

State locations

Path	Contents
<native-config-root>/config.json	Models, keys, MCP, UI (0600)
<native-config-root>/settings.json	Permissions defaultMode + allow/deny/ask (preferred for rules)
<native-config-root>/sessions/	Session snapshots
<native-config-root>/projects/<key>/memory/	Persistent memory
<native-config-root>/{agents,skills,legions,teams,plugins}/	Your assets (L1 default skills land under skills/)
<native-config-root>/direct-connect.json	serve discovery lockfile

<native-config-root> resolves as HIPMMCODE_CONFIG_DIR → else CLAUDE_CONFIG_DIR (v0.16.0+) → else HIPMMCODE_HOME → else ~/.hipmmcode. For a clean-room run, use HIPMMCODE_CONFIG_DIR=$(mktemp -d) hipmmcode. CLAUDE_CONFIG_DIR always selects the separate Claude compatibility tree for imports; when HIPMMCODE_CONFIG_DIR is unset it is also the native-root fallback.

Still stuck?

• hipmmcode integration — the embedded integration handbook.
• /release-notes — what changed recently.
• GitHub issues.