# When the agent gets stuck

> What to check when your coding agent stops, loops or skips a step while building from a starter kit, and how to tell AgentGid what in the kit was wrong.

Source: https://agentgid.com/docs/kits/when-agent-gets-stuck/ · Updated 2026-10-14

Most problems come from the setup, not the plan. Check these in order.

## The agent ignores the brief

- The kit files must sit at the top level of the project folder, and the agent must be started in that folder.
- Claude Code reads `CLAUDE.md`, which imports `AGENTS.md`; keep both.
- Copilot in VS Code reads `AGENTS.md` only when the `chat.useAgentsMdFile` setting is on.
- Gemini CLI needs `AGENTS.md` in `context.fileName`; Aider needs `--read AGENTS.md`.

## MCP tools are missing

The brief lists MCP servers under **Tools you have**. If their tools do not show up, either they are not approved yet (Claude Code holds the servers of a project `.mcp.json` as "Pending approval" until you accept them), or the config was added after the session started. Approve them or restart the agent in the folder. Until then the agent can use the links in the brief.

## A step keeps failing

- Look at what its **Done when** check printed. The step-by-step prompt makes the agent show it.
- Check the install: `install.txt` has the exact versions, and the brief says which runtime version is needed.
- Read **Known traps** in `AGENTS.md`: they are problems that test builds and the official docs showed with these parts.
- The whole-plan prompt tells the agent to stop and tell you what it tried when a check still fails after two real fixes. Read what it tried and help it with the next fix, or swap the part in the [kit builder](https://agentgid.com/build/).

## It asks you for something

That is by design. The brief tells the agent to stop and ask for an account, a key, a payment, or a part the brief does not list. Give it what it asks for, or tell it to leave that part out.

## Tell AgentGid what was wrong

Every brief has a section **When this brief is wrong**. The agent keeps a list of what was wrong, missing or out of date in `PROGRESS.md`, and when it finishes it can send that list through the AgentGid MCP server with `report_kit_issue`. Only AgentGid's editors read those reports. Keys, personal data and your code stay out of them.

You can also leave a comment on the recipe page (you sign in first), or write to [hello@agentgid.com](mailto:hello@agentgid.com).