Troubleshooting and FAQ

Use this checklist when something is not working. Most problems come from missing files, wrong paths, or unsynced context.

Common issues

SymptomLikely causeFix
"Command not found" in ClaudeFiles missing from .claude/commands/Re-copy session-commands/ files and restart Claude
Session commands complain about .current-sessionPointer file missingCreate empty file .claude/sessions/.current-session
Agent not respondingAgent file not in .claude/agents/ or name typed wrongVerify file path and reference with @filename.md
Prompt missingPrompt not placed in .claude/prompts/Copy template or reference full path
Context staleclaude.md or gemini.md not updatedEdit files, run /init or equivalent in each tool

Diagnostic checklist

  1. List directories: ls .claude or dir .claude
  2. Ensure agents/, commands/, prompts/, sessions/ exist
  3. Open agents/INDEX.md to confirm agent inventory
  4. Check permissions if using a shared workspace
  5. Pull latest toolkit changes if using a submodule

FAQ

Can I customize agents?

Yes. Clone the file, edit instructions, and keep both the original and custom versions in source control.

Should session logs be committed?

Commit for transparency, skip for sensitive work. Follow team policy.

How do we update the toolkit?

Pull the latest version, review diffs, re-run the setup checklist, and inform the team.

Does the toolkit work on Windows, macOS, Linux?

Yes. All assets are plain text. Use PowerShell, Command Prompt, or Bash to copy files.