12 Troubleshooting
12.1 Setup problems
12.1.1 claude-agent-coders: command not found
The short name works only in terminals opened after you first ran the script. Open a new terminal, or use the full path:
~/shared/workshop/claude-agent-coders12.1.2 “That workshop code is not right”
Check the code with your organizer and try again.
12.1.3 “That key was not accepted”
Paste the whole key, starting with sk-. If it still fails, ask your organizer.
12.1.4 “A key for … was already issued”
You, or someone using your name, already signed up. Ask your organizer.
12.1.5 “All workshop keys are handed out”, “sign-up is closed” or “has ended”
Ask your organizer.
12.1.6 “not set up yet” or “Could not reach the workshop gateway”
The gateway is not running. Ask your organizer.
12.1.7 I have a key from an earlier workshop
Forget the old key, then start again and enter the new code:
claude-agent-coders --reset
claude-agent-coders12.1.8 gh auth login or gh repo create fails
Run gh auth status to see whether you are logged in. If not, run gh auth login again and choose GitHub.com, HTTPS, Yes (authenticate Git), and Login with a web browser. If gh repo create says the name already exists, pick a different repository name.
12.2 Budget problems
12.2.1 “Budget exceeded”
Your key has hit its spending limit. Ask the organizer — they can increase it or issue a new key.
12.2.2 “Key expired” or “Key blocked”
The key’s time limit is up, or it was switched off. Ask the organizer for a new one.
12.2.3 How to check your remaining budget
claude-agent-coders --budgetSpending shows up about a minute after each request.
12.3 Agent behavior problems
12.3.1 Agent gives generic answers without reading files
Some models (especially open models) don’t use file-reading tools reliably. Try:
- Being explicit: “Use the read tool to look at
README.md, then answer.” - Switching to a Claude model, which handles tool use more reliably.
12.3.2 Agent seems confused or stuck
The conversation may have gotten too long. Run /clear and start fresh. If you have handoff notes in notes/, tell the agent to read those for context.
12.3.3 Agent makes changes you didn’t ask for
Review what the agent is doing before approving. Most tools ask permission before writing files. If it’s going off track, interrupt it and clarify what you actually want.
12.3.4 Agent is working in the wrong folder
Claude Code works in the folder you start it from. Quit (/exit), cd into your repository, and start claude-agent-coders again.