The short answer
Choose Agent when a Godot task requires several connected steps, such as inspecting project files, editing a script, and checking the result. State the outcome and constraints, attach or name the relevant project evidence, then follow the visible progress and tool activity. Without active project rules, read-only tools can run automatically and project-changing tools ask for approval by default. When res://AGENTS.md project rules influenced the run and Skip approval prompts is off, every tool—including read, list, and search—requires approval. Review the final files and run the affected scene yourself.
Use Agent for a bounded, multi-step outcome
Agent Mode is available on Pro and Ultra plans. It is most useful when the task needs GDSense to gather evidence, perform a sequence of supported actions, react to results, and continue toward one defined outcome. A short explanation or one isolated snippet is usually clearer and faster in Chat.
A strong task names the desired behavior, the project area in scope, what must not change, and how you will know it worked. That boundary gives the Agent a stopping condition and makes each proposed action easier to evaluate.
Inspect res://scripts/player_controller.gd and the Player scene. Fix the duplicate jump that happens after landing. Keep the existing input actions and public signals. Do not edit files outside res://scripts and res://scenes/player.tscn. Explain the cause, make the smallest change, and run the relevant project check.| Task shape | Use | Why |
|---|---|---|
| One answer or explanation | Chat | You control the attached context and receive one response at a time. |
| One reviewed code transformation | Quick Edit or Refactor | The focused edit opens a before-and-after review flow. |
| Several connected project steps | Agent | The Agent can inspect, act, report progress, and respond to tool results. |
Give the Agent a starting point, not the whole project
Agent Mode automatically sends a shallow tree of project file and folder path names, up to the plugin’s documented depth, so the Agent can see how the project is arranged. That tree does not include file contents and excludes hidden folders and the addons directory. The Agent can use supported read and search tools when it needs actual content.
Use @file, @openscript, @selection, @scene, or @node to point at relevant evidence. In Agent Mode these commands become path or selection hints; the Agent reads what it needs through its tools. On a fresh Agent start, the optional res://AGENTS.md project rules may also be supplied. This is still not automatic ingestion of every project file.
- Name the scripts or scenes most likely to contain the behavior.
- State expected behavior and the reproducible failure.
- List public methods, signals, input actions, or files that must remain unchanged.
- Review res://AGENTS.md before starting work in an untrusted or newly cloned project.
Keep in mind: Do not include passwords, API keys, private tokens, or other secrets in the task, attachments, project rules, or files you direct the Agent to read.
Follow progress and respond when the Agent needs you
The Agent stream shows reasoning status, narration, tool calls, tool results, and its terminal state. Tool activity is grouped into the run so you can see what was read, listed, changed, or executed. If the Agent asks for a decision, answer the question to continue the same conversation.
You can stop a live run when its direction is wrong. If a run reaches its iteration limit, the plugin can offer Continue; use it only after checking the work already performed. A connection drop may reconnect and replay the session, while a permanent delivery failure can require canceling and starting again.
- 1
Read the plan and status
Check that the reported direction still matches the requested scope before approving project changes.
- 2
Answer clarifying questions
When the conversation says it is waiting for you, provide the missing product or project decision.
- 3
Stop or redirect early
Cancel a run that has left scope instead of waiting for a large proposal to finish.
Understand which Agent actions require approval
For a run that was not influenced by project rules, read-only tools such as reading, listing, searching, and inspecting project information execute without a confirmation dialog, while project-changing tools are queued for approval. The dialog previews the proposed operation so you can approve or reject it, and a rejection is returned to the Agent as a tool result.
Project rules are untrusted guidance, not authorization. When res://AGENTS.md project rules influenced the active Agent run and Skip approval prompts is off, the plugin requires approval for every tool call, including otherwise-safe read, list, search, and project-information tools. This rule is latched to that run so later tool calls keep the same protection.
Skip approval prompts is off by default and persists as an Agent setting when you enable it. With the toggle on, some file creation, editing, deletion, and scene editing can execute without per-action dialogs. Project runs and tests, writes under res://addons/, and credential-bearing file operations still require confirmation or are refused. Use the toggle only in a version-controlled project where you can inspect and revert changes.
| Action | No active project rules; Skip off | Active project rules; Skip off | With Skip approval prompts |
|---|---|---|---|
| Read, list, search, inspect project info | Runs automatically | Confirmation dialog for every call | Runs automatically |
| Create, edit, or delete project files; edit a scene | Confirmation dialog | Confirmation dialog for every call | May run without a dialog when not specially protected |
| Run the project or a test | Confirmation dialog | Confirmation dialog for every call | Still requires confirmation |
| Target res://addons/ or a credential-bearing file | Protected | Confirmation or refusal | Still requires confirmation or is refused |
Keep in mind: Approval controls reduce accidental changes; they do not prove that an approved edit is correct. Keep version control active and inspect the resulting diff.
Verify the result before calling the task complete
The Agent can report what it changed and can run supported checks, but the Godot project remains the source of truth. Reopen modified scenes or reload the project when the editor has stale resources, inspect every changed file in version control, and exercise the gameplay path that originally failed.
- The changed files are inside the scope you specified.
- The diff preserves the public methods, signals, and input actions you protected.
- Godot loads the modified scripts and scenes without parse or resource errors.
- The original reproduction now passes and nearby edge cases still work.
- Unexpected generated files or broad rewrites are rejected or reverted.