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-flash / deepseek-v4-pro (not marketing date tags). Prefer channel deepseek-anthropic for native search.
• Images work on deepseek-flash (native multimodal). Pixels go up through the Files API. There is no one-turn detour to a separate vision SKU. deepseek-v4-pro does not accept images.

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.

LM Studio / local OpenAI-compatible servers stall or never run tools (v1.0.5)

Paste http://host:1234 — hipmmcode appends /v1. Tool schemas always include properties. Local prefill can wait 10 minutes; idle after first text is 5 minutes; HTTP idle read is 10 minutes. In Auto mode, read-only MCP tools such as kb_status and kb_search skip the classifier; Bash and Write may still be denied on a single local GPU that cannot classify quickly.

Nothing works with the VPN off

Two usual causes:

1. The channel goes to the official address. xai-oauth, and xai without XAI_BASE_URL, connect to api.x.ai, which needs a VPN in mainland China. A third-party gateway belongs in XAI_BASE_URL; GROK_MODELS_BASE_URL has no effect. After binding a platform plan, switch to inclusive-grok / premium-grok / vip-grok with /model. /status shows the address the current channel really uses.
2. A local proxy is left in your shell. From v1.3.1 a local proxy that is down is skipped automatically; with older versions run unset https_proxy http_proxy all_proxy HTTPS_PROXY HTTP_PROXY ALL_PROXY before starting.

See Third-party Grok gateway and VPN.

The phone cannot connect to /rcl

Make sure phone and computer share a network (or are both in Tailscale) and that the address in the QR code is the computer's LAN address. Older versions could put a VPN's 198.18.0.1 there; upgrade to v1.3.1. hipmmcode remote-control --list shows the remote sessions and the local relay. See Remote control.

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.

@ does not show a renamed session

@ only lists custom titles or alias-shaped names (letter first, then letters, digits, ._-). Auto-generated first-message titles stay out of the picker. On desktop, rename the sidebar title to something like alpha — no extra /peer step. Both sessions must be running.

Desktop MCP add fails

Public HTTP usually needs only the URL. Authenticated servers need Authorization or extra headers; local processes use STDIO with command, args, and env. After saving, confirm the server is connected in settings.

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.