Troubleshooting — TopGun Help

Quick diagnosis: run node topgun-tools.cjs list-registries to see the current status of all adapters, and node topgun-tools.cjs show-manifest to inspect the last audit result.

Registry Unavailable / 3+ Registries Down

Registry timeout or connection error

Warning

Symptoms

TopGun › ⚠ skills.sh timed out after 10s — skipping TopGun › ⚠ 3 or more registries failed — connectivity warning TopGun › ✓ Found 3 candidates across 2 registries (reduced coverage)

Cause

One or more registry adapters did not respond within the 10-second timeout. This is typically a temporary network issue or registry downtime. TopGun continues with the adapters that succeeded.

Fix

Wait and retry. Most registry outages are brief. Run the same /topgun command again in a few minutes.
Check your internet connection. Confirm you can reach skills.sh and github.com from a browser.
Use --offline with cached results. If you ran a similar query recently, /topgun <task> --offline uses cached registry data and skips all live requests.
Restrict to reachable registries. Use --registries to target only the registries that are online: /topgun <task> --registries npm,smithery.

SENTINEL File Missing from Plugin

Bundled SENTINEL file not found inside TopGun plugin

Pipeline abort

Symptoms

TopGun › ✗ Cannot Read $CLAUDE_PLUGIN_ROOT/skills/sentinel/SKILL.md TopGun › Bundled SENTINEL v2.3.0 missing from plugin TopGun › Pipeline aborted at SecureSkills stage

Cause

SENTINEL ships bundled directly inside the TopGun plugin at skills/sentinel/SKILL.md. If that file is missing, the plugin cache is corrupted or incomplete. The SecureSkills stage cannot run without it.

Fix

Reinstall TopGun. Run /plugin install alo-labs/topgun in Claude Code. This will fetch the latest plugin release, which includes the bundled SENTINEL file.
Verify the bundled file exists. After reinstall, check that ~/.claude/plugins/cache/topgun/topgun/<version>/skills/sentinel/SKILL.md is present.
Clear stale cache. If reinstall still fails, remove the plugin cache directory and retry the install.

Install Failure

/plugin install fails or silently does nothing

Install error

Symptoms

TopGun › ✗ /plugin install returned non-zero exit TopGun › Falling back to local-copy install method… TopGun › ✓ Skill installed via local-copy fallback

Cause

There is a known intermittent bug in the Claude Code plugin system where /plugin install fails silently or returns an error for valid plugin manifests. TopGun detects this and automatically falls back to a local-copy install: it copies the audited SKILL.md directly to the Claude Code skills directory.

Fix

Trust the fallback. The local-copy fallback installs the same audited skill content. The SENTINEL audit result applies equally to both install methods. If you see "installed via local-copy fallback", the skill is functional.
Verify the skill is active. After a local-copy install, the skill should appear in /plugin list. If it doesn't, run /topgun <task> --reset to retry the full pipeline.
Update Claude Code. The plugin system bug is tracked upstream. Updating to the latest Claude Code version may resolve it: npm update -g @anthropic/claude-code.
Check install-log.json. Run node topgun-tools.cjs show-install-log to see exactly what was installed, when, and via which method.

Pipeline Resume Issues

Resume picks up stale state from a previous query

Unexpected behavior

Symptoms

TopGun › Resuming from state.json (stage: CompareSkills) TopGun › Query: "git automation" — but I asked for "test runner"

Cause

TopGun's resume logic checks for any existing state.json at startup. If a previous pipeline was interrupted and never completed, it will resume — even if your new query is different.

Fix

Use --reset to start fresh. Run /topgun <your task> --reset to discard the stale state and run a new pipeline from the beginning.
Or clear state manually. Run node topgun-tools.cjs reset-state to delete state.json, then run your /topgun command normally.

Resume skips FindSkills but registry coverage has changed

Info

Symptoms

TopGun › Resuming from state.json (stage: SecureSkills) TopGun › Skipping FindSkills and CompareSkills — already completed

Cause

This is expected behavior. When resuming, TopGun skips completed stages. If you added a new registry token or want to search with updated coverage, use --reset to run fresh.

Fix

If you want fresh registry results (e.g. after adding a GitHub token), run with --reset.
If you're happy to continue auditing the previously selected winner, let the resume proceed — it will run SENTINEL from where it left off.

Auth Token Issues

GitHub rate limit hit — reduced candidate coverage

Warning

Symptoms

TopGun › ⚠ GitHub adapter: rate limit reached (60 req/hr) TopGun › ⚠ GitHub results may be incomplete

Cause

The GitHub adapter uses the unauthenticated API by default, which is limited to 60 requests per hour. In heavy use, this limit is quickly exhausted.

Fix

Add a GitHub token. Create a personal access token with read:public_repo scope at github.com/settings/tokens, then store it: node topgun-tools.cjs set-token github <token>.
Authenticated limit is 5,000 req/hr — sufficient for any TopGun usage pattern.

Token stored but registry still returns unauthenticated results

Info

Symptoms

TopGun › ⚠ GitHub adapter: using unauthenticated API # Even though you set a token

Cause

The token may have been stored under a different key, or the Keychain entry was created by a different user account. TopGun reads tokens at pipeline start — restarting Claude Code after setting a token is required.

Fix

Verify the token is stored correctly. Run node topgun-tools.cjs get-token github — you should see a masked token value ending in the last 4 characters.
Restart Claude Code after setting a token. TopGun reads credentials at startup; a running instance won't pick up new tokens without a restart.
Re-set the token. If get-token returns nothing, run set-token again and confirm the Keychain permission dialog if one appears.

← Previous Command Reference