Help
Troubleshooting
The failure modes we actually see, and their fixes.
Git Bot
| Symptom | Fix |
|---|---|
| The review can't compare versions, or reviews the wrong diff | The checkout step needs fetch-depth: 0 - the Action compares the PR against its merge base, which takes history. |
| Authentication errors from GitHub on posting the comment | GITHUB_TOKEN is provided automatically by GitHub - do not create a secret with that name. And the workflow needs the permissions block from the template: issues: write is required because GitHub's PR comment API is the issues endpoint. |
| PRs that touch prompts don't trigger a review | The workflow's paths: filter and the Action's file_pattern input select together - keep them in sync. Draft PRs are skipped until marked ready. |
| models.md seems ignored | The most specific glob wins, and an unmatched path falls back to Hosho's own detection. A typo never fails a review - check the Job Summary to see what was applied. |
MCP
| Symptom | Fix |
|---|---|
| The review dies after about a minute | Your client's per-server timeout is at its default. A full review runs 5-10 minutes - use the install snippets, which set timeout: 900000. |
| Every Hosho tool appears twice | You installed both the manual MCP config and the co-presence plugin - they register the same server under two names. Remove the manual hosho-prompt-review entry and keep the plugin. |
| 401 / key errors | Invalid API key format means the value does not start with pfr_ (a paste took the quotes or lost the prefix). API key not found means the key was revoked or mistyped - mint a fresh one at /setup/mcp. A disabled key says so - write to otto@hoshoai.com to restore access. |
| "This report has expired" on a report link | Report pages are short-lived - re-run the tool to generate a fresh one. |
Co-presence
| Symptom | Fix |
|---|---|
| hosho-channel shows as failed | Usually a missing key: the plugin reads HOSHO_API_KEY from your shell, not from an MCP client config. Export it (put it in your shell profile) and restart Claude Code. |
| The agent doesn't wake when you message it | Confirm you launched with the channel flag from the session command. Messages queue either way - the agent catches up on its next turn. |
Still stuck?
Write to otto@hoshoai.com - it reaches a human who works on the product.