The short answer
GDSense attaches the script you have open to Chat questions automatically, so most questions about your current code need no command at all. Use @file when you know a res:// path and optionally want a line range or named symbol. Use @openscript to pin the open script explicitly, and @selection to capture the highlighted lines in the active script editor. Type @ to open the command picker; @file also opens a searchable project-file picker. In Agent Mode these commands provide path or selection hints so the Agent can read relevant content with its tools.
Start with the script GDSense attaches for you
When you ask a Chat question, GDSense includes the script open in the editor and shows it as a chip above the prompt box. Scripts and shaders are attached; scenes, resources, and data files are attached only when you ask for them with @file or @scene. The script travels once per conversation and again only after you change it, so follow-up questions stay lean.
Remove the chip with its × to leave the script out of a single message, or turn off Attach the open script automatically under Settings → Context. When you type @openscript or an @file that names the same script, your command takes over and the automatic copy steps aside, so the file is never sent twice.
Keep in mind: A script that contains a recognized private key or live API key is never attached automatically. Its chip says so instead, and the file goes only if you name it with @openscript or @file. Keep secrets out of scripts where you can, for example in environment variables.
Add runtime evidence with @errors and @log
In GDSense 1.4.0, choose Attach errors on the Errors from last run (N) chip or use @errors to attach captured game errors; @log attaches recent game output in Chat and Agent Mode. Errors attach only through your explicit action. These complement @file, @openscript, @selection, @scene, and @node. Review attachments and logs for secrets before sending.
Choose the smallest file or script command
The @ picker lists the available context commands. Choosing @file opens fuzzy search over allowed project files. The picker excludes Godot internals, GDSense’s own addon folder, repository internals, and credential-bearing files. A blocked file cannot be attached by typing its path manually either.
| Command | What it identifies | Best use |
|---|---|---|
| @file | An allowed res:// file, optional line range, or named symbol | A saved file you can name precisely |
| @openscript | A snapshot of the script currently open in the editor | Pinning the active script explicitly for later turns |
| @selection | The highlighted code plus its path and line numbers | One focused block or expression |
Use @file for a path, line range, or symbol
File paths must be inside res:// and use an allowed text-based project extension. Quote a path when it contains spaces. A line range limits the attached content, while a #symbol anchor selects a named function or symbol when the parser can locate it.
@file "res://scripts/player_controller.gd":24-68
The player sometimes receives a second jump after landing. Trace state changes only in this range and tell me what additional dependency, if any, you need before proposing a fix.@file res://scripts/player_controller.gd@file "res://scripts/player controller.gd":24-68@file "res://scripts/player_controller.gd"#apply_gravityKeep in mind: A narrower range can hide a dependency. Include the whole function or a directly related caller when the answer depends on state set outside the selected lines.
Use @openscript to pin the current editor script
@openscript captures the current CodeEdit content and its res:// path when the request is prepared. In a Chat session, the plugin keeps that snapshot pinned for later turns so follow-up questions retain the same evidence. Use it when you want one specific version of a script to stay in front of GDSense for the rest of the conversation.
@openscript
Explain how this state machine enters and exits the dash state. Identify any transition that can leave velocity locked, but do not rewrite the script.- Open the intended script before sending the request.
- Use a new @openscript capture after making edits that the pinned copy should reflect.
- Start a new Chat when you do not want earlier pinned script context carried forward.
Use @selection for highlighted code
@selection reads the active script editor’s highlighted text and records its file path and line numbers. It is the most precise choice for an expression, signal callback, or branch that needs explanation. If nothing is selected or no suitable script editor is active, the command reports an error instead of guessing.
@selection
Explain which values can reach this branch and whether the null check covers a freed Godot object. Give me a verification step before any code suggestion.Know what is transmitted in Chat and Agent Mode
In Chat, the plugin expands file and script commands into structured context before the request is sent. A Chat request carries your prompt, the open script and compact project map when they are new to the conversation or have changed, and any explicit attachments. In Agent Mode, commands and the open script become path or selection references; the Agent receives the project map and a shallow path-name tree and calls supported read tools for actual content.
Neither workflow sends every project file. Fresh Chat and Agent-start requests may additionally include your Settings rules and the optional res://AGENTS.md project rules. Retry preserves the original context and rules, and autocomplete does not use AGENTS.md.
Keep in mind: Review explicit attachments for secrets and private data. Do not attach credential files or paste credentials into the prompt.