Troubleshooting

Setup problems

`claude-agent-coders: command not found` or `agy-agent-coders: command not found`

The short command names work only in terminals opened after you first ran the launcher script (the scripts add ~/.local/bin to your PATH). Open a new terminal, or use the full paths:

Claude Code: ~/shared/workshop/claude-agent-coders
Antigravity: ~/shared/agent-coders/agy-agent-coders

“agent-coders guard: …”

The safety guard installed by agy-agent-coders stopped a command. See Guardrails for the full list.

Blocked (git reset --hard, git push --force without lease, git clean -f, rm -r outside your project, pushing to main, deleting a repository): this is intentional. Tell the agent to use a safe alternative, such as git stash, a soft reset, or a branch and a pull request. If you really want one of these, run it yourself in a terminal.
“needs the user to say yes first” (merging a pull request, deleting a branch, closing an issue, a pull request into someone else’s repository): the agent should tell you what it wants to do and ask. If you agree, say so, and it will run the command again.

Antigravity prompts for approval on everyday commands

If Antigravity prompts you to approve simple commands like ls or quarto, you may have started plain agy instead of the team launcher. Quit and restart with:

agy-agent-coders

You can check what commands are currently allowed to run without asking by running:

agy-agent-coders --check

Antigravity prompts for approval on `pip`, `cp`, or `rm`

This is normal and expected. The team launcher whitelists safe, everyday commands (quarto, R, python3, git, directory listing, etc.), but intentionally leaves package installations (pip), file copies, and deletions to require explicit user approval. Review the proposed command and approve it if appropriate.

“That workshop code is not right”

Check the code with your organizer and try again.

“That key was not accepted”

Paste the whole key, starting with sk-. If it still fails, ask your organizer.

“A key for … was already issued”

You, or someone using your name, already signed up. Ask your organizer.

“not set up yet” or “Could not reach the workshop gateway”

The gateway is not running. Ask your organizer.

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-coders

GitHub refuses a push or `gh` command

Check these before widening the token:

Are you logged in with the token? Run gh auth status. If you are not logged in, or it shows a browser login, run gh auth login again and choose Paste an authentication token.
Is the remote HTTPS? Run git remote -v. If it starts with git@github.com:, switch it: git remote set-url origin https://github.com/YOUR-USERNAME/my-quarto-book.git.
Is this repository on the token? At https://github.com/settings/personal-access-tokens, open the token and check that the repository is in its selected repositories, and that Contents (and Pull requests or Issues, if that is what failed) are Read and write.
Has the token expired? Make a new one with the same settings and log in with it again.

gh repo create does not work with this token, because it cannot create repositories. Create new repositories on GitHub’s website.

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.

Sandbox fails with `agy --sandbox`

Do not use --sandbox. The JupyterHub container environment does not support nested container namespaces.

Non-interactive `agy -p` exits early

agy -p "..." stops immediately at the first command that requires confirmation. For clinic exercises, use interactive mode (agy-agent-coders) instead.

Budget problems

“Budget exceeded”

Your key has hit its spending limit. Ask the organizer — they can increase it or issue a new key.

“Key expired” or “Key blocked”

The key’s time limit is up, or it was switched off. Ask the organizer for a new one.

How to check your remaining budget

claude-agent-coders --budget

Spending shows up about a minute after each request.

Agent behavior problems

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.

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.

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.

Agent is working in the wrong folder

Agents work in the folder you start them from. For Antigravity, this folder also defines the boundary that the safety guard protects. Quit (/exit), cd into your repository, and launch the agent again.