AI coding assistants
AI coding assistants such as Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, and Devin often guess at SDK APIs. The results can look right and still be wrong. We publish an instruction file, AGENTS.md, with each SDK release. It tells these assistants how to use the Treble SDK's public API, including coordinate conventions, units, bulk APIs, and cost estimation.
Download
| File | Purpose |
|---|---|
| AGENTS.md | The SDK rules. Supported by most coding assistants. |
| GEMINI.md | Only needed for Gemini CLI. It imports AGENTS.md. |
To add the files to your project:
- Right-click the file link above and choose Save link as. If the file opens in the browser instead, save the page with Ctrl+S (Windows and Linux) or Cmd+S (macOS).
- Save it in the root of the project folder where you write Treble SDK code, next to your notebooks or scripts.
- Keep the file name exactly
AGENTS.md(orGEMINI.md). Make sure the browser or editor does not add an extension such as.txt.
The files are updated with some SDK releases. Download them again after you update the SDK.
If your project already has an AGENTS.md, copy the Treble SDK rules into it, or save the file as treble-sdk.md and reference it from your own AGENTS.md.
Set up your assistant
| Assistant | What to do | Vendor documentation |
|---|---|---|
| Claude Code | Nothing more. Claude Code reads AGENTS.md when the project has no CLAUDE.md. If you have a CLAUDE.md, add the line @AGENTS.md to it. Also add it for older Claude Code versions. | Memory and CLAUDE.md |
| Cursor | Nothing more. Cursor reads AGENTS.md automatically. | Rules |
| GitHub Copilot | Nothing more for VS Code and the Copilot coding agent. | Repository custom instructions |
| OpenAI Codex | Nothing more. Codex reads AGENTS.md automatically. | AGENTS.md in Codex |
| Devin and Windsurf | Nothing more. Both read AGENTS.md automatically. | Devin, Windsurf |
| Gemini CLI | Also download GEMINI.md. Alternatively, add AGENTS.md to context.fileName in .gemini/settings.json. | GEMINI.md |
Other tools that support the open AGENTS.md format pick up the file automatically.
Chat assistants
Chat assistants such as ChatGPT, Claude, and Microsoft Copilot cannot see your project folder, so they do not read AGENTS.md on their own. Attach the file to the conversation. If the assistant supports projects, add the file to the project's files or instructions so every chat in the project uses it. For Claude, see projects.
Jupyter notebooks
Coding assistants in editors such as VS Code and Cursor look for AGENTS.md in the folder that is open as the workspace. Open the folder that contains AGENTS.md, not just a single notebook file. If your notebooks are in subfolders, keep AGENTS.md in the top-level folder and open that folder.
Stay in control of tokens and credentials
An assistant that can run code can also start simulations that spend tokens. The instruction file tells the assistant to show you the estimate and ask before starting simulations. You should still:
- Never paste your Treble credentials into a chat. The SDK reads your credentials file from your computer. See Storing your credentials.
- Read the token estimate yourself before you confirm a run.
- Try a GA simulation or a small model first, then run DG or hybrid simulations and large batches.
- Check your balance with
tsdk.get_token_status()before large jobs. See Starting simulations and spending tokens.
What the file covers
The rules are short and point to this documentation and the API reference for details. They cover:
- the public import pattern, and not calling
_-prefixed internals; - factory methods and parameter names for sources and receivers;
- units, the Z-up coordinate system, and the
Rotation(0, 0, 0)facing (+X); - simulation types and their watertight and crossover requirements;
- bulk APIs instead of Python loops, and IR collections for many results;
- unpadded IR data, SDK filters, and the built-in plotting;
- token estimates, and asking you before starting simulations;
- keeping credentials out of chats, logs, and example code.
Instruction files guide the assistant, but they do not guarantee correct code. Review generated code before you run simulations that spend tokens.