The short answer
Use Chat Mode for explanations, debugging guidance, design questions, and other work where you want one answer at a time from the context you attach. Use Agent Mode when the outcome requires several connected steps and supported project tools, such as inspecting files, proposing edits, and checking results. Chat does not operate project tools. In Agent runs without active project rules, read-only actions can run automatically and protected actions prompt by default. If res://AGENTS.md project rules influenced the run and Skip approval prompts is off, every tool requires approval. You can continue either kind of conversation from local History.
Compare Chat and Agent side by side
| Question | Chat Mode | Agent Mode |
|---|---|---|
| Best task shape | A focused question or one response at a time | A bounded outcome with several connected steps |
| Project access | Uses prompt content and explicit attachments | Receives path hints and can use supported project tools |
| Automatic project overview | No project tree | Shallow file and folder path-name tree; no file contents |
| Changes files | No direct project tool execution | Can propose and execute supported file or scene changes |
| Approvals | Not applicable to Chat responses | Read-only tools can run automatically without active project rules; active project rules force approval for every tool when Skip is off |
| Plan access | Available with GDSense access | Available on Pro and Ultra |
| Credits | Selected reasoning mode is billed per request | Selected reasoning mode is billed per completed turn; no extra Agent multiplier |
Choose Chat when you want to stay in the driver’s seat
Chat is the better default for learning an API, understanding selected GDScript, narrowing down an error, reviewing an approach, or asking for a small code example. You decide which file, selection, scene, or node content accompanies the prompt, then ask follow-up questions in the same session.
A Chat response may contain code, but it does not directly apply that code through Agent tools. Copy only the parts you understand, or use Quick Edit or Refactor when you want a purpose-built before-and-after review.
@selection
Why can this signal connection fire twice after the scene reloads? Explain the likely lifecycle issue first, then show the smallest correction. Do not rename the signal.Choose Agent when the work depends on tool results
Agent is appropriate when the next step depends on what the previous inspection or check reveals. It can read and search supported project files, list paths, inspect project information, propose file and scene changes, and run supported project checks. Tool results return to the same run so it can continue.
The Agent’s shallow path-name tree helps it navigate, but it is not the project’s contents. Give it a clear starting path and scope. Keep approval prompts enabled unless you intentionally accept the risk of allowing eligible file operations to execute without a dialog. When project rules influenced the run, keeping Skip approval prompts off also makes every read, list, search, and inspection tool ask first.
Trace why the Door scene never receives the player's interact signal. Start with res://scenes/door.tscn and res://scripts/door.gd, inspect only direct dependencies, make the smallest fix, and check the project output. Preserve the existing signal name and input action.Keep in mind: Use version control for Agent work. An approval dialog shows intent and parameters, not a guarantee that the resulting behavior is correct.
Expect context commands to behave differently
In Chat, context commands expand the requested file, selected code, open script, scene structure, or node details into the request. In Agent Mode, the same commands identify relevant paths or selections and the Agent uses read tools to retrieve content as needed. This keeps the Agent free to inspect related evidence within your stated scope.
The optional res://AGENTS.md project rules may be read on a fresh Chat or Agent-start request. Retry preserves the original rules and context rather than rereading the file. Autocomplete does not use AGENTS.md.
- Use explicit attachments in Chat when the answer depends on project evidence.
- Give Agent a start path plus an allowed scope, even though it receives the shallow path tree.
- Start a new request when you need freshly edited project rules instead of retrying an older request.
Move from discussion to execution deliberately
A useful pattern is to clarify architecture or constraints in Chat, then promote that saved Chat conversation into Agent Mode when you are ready for multi-step execution. Promotion is one-way: the history entry becomes an Agent conversation, and the first Agent send seeds the work with the prior Chat context.
You can also stay in Chat and start a separate Agent conversation with a concise task summary. That preserves the original discussion unchanged and gives the Agent a tighter starting brief.
- 1
Resolve the design question in Chat
Identify the intended behavior and constraints before any project-changing work.
- 2
Choose promotion or a fresh Agent task
Promote when the full discussion is useful; start fresh when a short implementation brief is safer.
- 3
Review the Agent result in Godot
Inspect the diff, reload changed resources when needed, and reproduce the target behavior.