AI Tools Troubleshooting

Cursor Agent CLI

Failed to reach the Cursor API (Herdr / Ghostty)

Usually not Herdr itself. Two common causes on this Mac:

1. CNB OpenVPN full-tunnel

OpenVPN Connect often pulls redirect-gateway def1 (0/1 + 128.0/1 via 10.255.248.x). Public IPv4 (including api2.cursor.sh) then rides the VPN. When the tunnel flaps, agent exits with that error.

cnb-openvpn-mac doctor
cnb-openvpn-mac patch-profiles   # once per profile import
cnb-openvpn-mac split            # drop full-tunnel routes; keep CNB LAN

Profile copy and import steps are in OpenVPN.

2. Herdr panes lost macOS DNS (scutil --dns → “No DNS configuration available”)

After VPN route changes, a long-lived Herdr server can leave pane shells unable to resolve via getaddrinfo while dig still works. Symptom in the pane: curl: (6) Could not resolve host. Restart the Herdr server so panes respawn with a fresh configd session:

herdr server stop
# reattach / reopen Herdr (starts a new server)
scutil --dns | head -5    # in the pane - must show resolvers again
agent status

Confirm default route is Wi-Fi/en0, not utun* for 8.8.8.8:

route -n get 8.8.8.8 | rg 'gateway|interface'
agent status

Codex CLI

Desktop: Missing environment variable: CLI_PROXY_API_KEY

Codex CLI works but Desktop fails when the key is only exported in the shell. GUI apps do not load ~/.zshrc.

macOS fix (stow-managed LaunchAgent):

make stow-bin stow-launchd
launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/local.cli-proxy-gui-env.plist" 2>/dev/null || true
launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/local.cli-proxy-gui-env.plist"
launchctl kickstart -k "gui/$(id -u)/local.cli-proxy-gui-env"
# Fully quit ChatGPT.app (Cmd+Q), then reopen
launchctl getenv CLI_PROXY_API_KEY | wc -c

If the log shows gopass failures, unlock gpg once (gopass show personal/saas/cli-proxy/code-01-api-key) and re-run kickstart.

After key rotation:

"$HOME/.local/bin/set-cli-proxy-gui-env.sh" refresh

/goal Not Visible

codex features list | rg '^goals'

The expected state is stable true. If it is false, reinstall the repo-managed config and restart Codex:

make stow-codex
codex features enable goals

The dotfiles config also pins features.goals = true directly in ~/.codex/config.toml.

Config Health

codex doctor --summary --ascii
codex mcp list
codex plugin list

Only ~/.codex/config.toml is managed by this repo. Auth files, history, SQLite state, logs, and caches should remain local.

miudb MCP

Check the miudb MCP command exposed by the CLI:

miudb describe mcp serve --output json

Cursor reads the same server from ~/.cursor/mcp.json.

Caution

Keep ~/.cursor/mcp.json local-only — existing MCP server entries may carry tokens. The miudb entry should be:

{
  "command": "miudb",
  "args": ["mcp", "serve", "--transport", "stdio"]
}

CodeCompanion Issues

API Key Problems

# Check Gemini API key
echo $GEMINI_API_KEY

# Set API key temporarily
:lua vim.env.GEMINI_API_KEY = "your-key-here"

Chat Not Responding

# Check network
ping generativelanguage.googleapis.com

# Restart CodeCompanion
:CodeCompanion reset

Supermaven Issues

Suggestions Not Appearing

# Check if Supermaven is running (auto-starts)
# Try restarting Neovim

# Ensure not in a large file (>100KB can disable AI)

Performance Issues

# Supermaven uses proprietary model
# Check system resources
# Large files may slow suggestions

Database (miudb) Issues

Connection Failures

# List saved connections
:MiuDBConnections

# Select active connection
:MiuDBSelectConnection

# Check miudb CLI directly
miudb connections list --output json

Query Problems

# Run from Neovim
:MiuDBQuery

# Run from shell for debugging
miudb query run --connection <name> --sql 'select 1 as one' --output json