Troubleshooting

Model config is missing

If OPENROUTER_API_KEY is set, start without config:

topchester -m openrouter/google/gemini-3.1-flash-lite

Inside the TUI, /model openrouter/google/gemini-3.1-flash-lite makes the same session-only selection. Run /connect openrouter when you want saved choices, or edit ~/.config/topchester/config.jsonc for a durable default. Custom providers must be defined in config.

For Codex ChatGPT models, run:

topchester auth login codex --device

Then check topchester auth status or topchester info.

Codex auth needs relogin

If a Codex request fails because the refresh token was revoked, expired, reused, or belongs to a different account, run:

topchester auth login codex --device

Topchester stores refreshed Codex OAuth credentials in ~/.config/topchester/auth.json and redacts token values in topchester auth status and topchester info.

Knowledge base is missing

Run:

/kb init

Then use /kb status and /kb sync to refresh project knowledge.

A command needs approval every time

Add a narrow project rule under tools.bash.allowExact or tools.bash.allow in topchester.jsonc. Use allowExact for a complete command string and allow for argv prefixes.

An MCP server exposes too much

Add enabledTools to the server config. If enabledTools is omitted, Topchester applies a V0 exposure cap and omits servers that exceed it.