Trae native reference
Start with the Trae setup.
Native mappings
Trae reads AGENTS.md only when Include AGENTS.md in the context is on (Settings > Rules & Memories). See loading and limits.
Rules
Sync always writes description, globs, and alwaysApply (Cursor's .mdc fields for when a rule applies), because Trae documents no default for a file without them.
alwaysApplyistrue, orfalsewhen the spec setsglobsother than a catch-all such as**/*. Atruerule omitsglobs.alwaysApply: falsewith noglobsuses the Claudepathslist, joined with commas.x-trae.scene: git_messagemarks a rule for AI-written commit messages.
Agents
Subagents docs. The body is the system prompt.
- Frontmatter:
nameanddescription(required); optionalmodel,tools,disallowedTools,mcpServers. toolsis written as a comma-joined string, since Trae uses Claude-style names (Bash,Edit,Glob,Grep,Read,Write,WebFetch,WebSearch, plusSkill,LSP,TodoWrite,mcp__<server>__<tool>).- Omit
toolsto load every available tool. - An explicitly empty list (
can: [],tools: [],tools: "", orx-trae.tools) writestools: "", which disables all tools. Import keeps this through later syncs. - Trae accepts only its built-in model IDs. A generic
modeldrops with a sync note. Usemodel: {trae: <id>}orx-trae.model. disallowedToolsandmcpServerscome fromx-trae.x-trae.disallowedToolsis a comma-separated list of blocked tools and wins overtools.- A name starts with an ASCII letter, ends with a letter or digit, uses only letters, digits, or hyphens, and has at most 50 characters. Sync rejects any other name.
- Subagents need Settings > Beta > Subagents > Enable Subagents Directory. Trae does not say whether it is on by default.
Skills
- Path:
.trae/skills/<name>/SKILL.md, withnameanddescription. - Files beside it (
examples/,templates/,resources/) are copied as they are. - A flat file under
.trae/rules/never loads as a skill.
Commands
Slash-commands docs. Frontmatter is only name and description (the documented fields). The body is the prompt. Trae reads commands up to 3 levels deep. Sync writes them flat.
MCP servers
MCP docs. A root mcpServers map.
- Stdio:
command(required),args,env. HTTP:url(required),headers. - Trae works out
typefromcommandorurl, so none is written. - A stdio
commandwith spaces fails to parse in Trae. - Trae has no per-server
disabledkey, only a project toggle (Settings > MCP).disabled: trueis dropped with a sync note.
Hooks
.trae/hooks.json is the project tier of Trae's hook configuration. agnostic-ai hook run tests hooks before a session, with Trae's event data, shell, and timeout.
- A
versionfield (always 1) wraps thehooksmap. Each event holds{matcher, hooks: [{type, command, timeout}]}groups. - Claude Code, Codex, OpenHands, and Qoder use the same shape, so one hook spec feeds all five.
- The
hook runcontext preview recognizes successful plain stdout onSessionStartandUserPromptSubmit. JSONhookSpecificOutput.additionalContextapplies to those events andPreToolUseandPostToolUse.Notificationignores stdout;Stopdoes not readadditionalContext. - Six events:
SessionStart,UserPromptSubmit,PreToolUse,PostToolUse,Stop,Notification. - Each entry takes
type(onlycommand),command, andtimeout(seconds, default 30). loop_limitcaps how often aStophook can block the agent (default 5).- Hook
tool_namevalues differ from subagenttools:Read,Write,Edit,Glob,Grep,LS,RunCommand,WebSearch,WebFetch,AskUserQuestion,Skill,mcp__<serverName>__<toolName>. There is noTodoWrite. - The terminal tool is
RunCommand, somatcher: Bashis written as is, raises a sync note, and matches nothing. matcherapplies toPreToolUse,PostToolUse, andNotificationonly. OnNotificationit selects a type (idle_prompt,permission_prompt, ...).- Project hooks do nothing until you enable them under Settings > Hooks and accept the security warning.
- Trae also runs Claude Code's hooks from
.claude/settings.jsonand.claude/settings.local.jsononce you turn on Import Hook configuration in CLAUDE (off by default, same warning). Syncingclaudeandtraethen runs every hook twice.
Ignore
Ignore docs. This is the file Trae's Settings > Indexing & Docs creates.
- It adds to
.gitignore, which Trae already honors. Specs are joined. Override withoutputs.trae.ignore-file. - On clients released before October 22, 2026, it keeps paths out of indexing and
@Foldercontext. Run a Build under Settings > Indexing & Docs after a sync, because the change applies only after re-indexing. - Trae removes Indexing & Docs from clients released on or after that date and does not say how
.trae/.ignoreapplies there.
Shared memory
With builtins: [memory], sync adds the native memory-trae-session-start hook for SessionStart to .trae/hooks.json.
- Once you enable project hooks in Settings > Hooks, it runs
agnostic-ai project -- hook memory --target traebefore the first message. It adds up to 6,000 bytes from the personal and project memory indexes. - Trae's own Memories stay available.
- Trae sets
TRAE_PROJECT_DIRto the hook's workspace, so the command finds that project's indexes even when its shell starts elsewhere. - The command uses the project's installed agnostic-ai package when one is declared. Install or upgrade it before starting Trae.
- If hooks are disabled, the shared memory rule still tells Trae to read the indexes.
Agents from older versions
For every current agent, sync removes a generated copy at the old .trae/rules/agent-<name>.md path.
Config keys
| Key | Default |
|---|---|
outputs.trae.rules-dir | .trae/rules |
outputs.trae.rules-mode | unset; set entry-point when Trae's Include AGENTS.md in the context switch is on |
outputs.trae.agents-dir | .trae/agents |
outputs.trae.skills-dir | .trae/skills |
outputs.trae.commands-dir | .trae/commands |
outputs.trae.hooks-file | .trae/hooks.json |
outputs.trae.ignore-file | .trae/.ignore |
outputs.trae.mcp-file | .trae/mcp.json |
Import
agnostic-ai import trae reads these back:
| Source | Becomes |
|---|---|
.trae/rules/*.md | rules, agents, and skills by filename prefix |
.trae/agents/<name>.md | <agents>/<name>.md, copied, minus the generated header |
.trae/skills/<name>/SKILL.md and .agents/skills/<name>/SKILL.md (+ bundled files) | <skills>/<name>/SKILL.md (folder copied as is) |
.trae/commands/<name>.md | <commands>/<name>.md |
.trae/hooks.json | one spec for consecutive commands with the same timeout in a matcher group, carrying loop_limit |
.trae/mcp.json (mcpServers.<name>) | <mcps>/<name>.yaml, a url-only entry becomes type: http |
.trae/.ignore | an ignore spec |
- Import reads
.trae/skills/first, then.agents/skills/. For the same folder name, Trae's own copy wins. - Shared skills keep the same checks for existing specs and generated assets. Sync still writes
.trae/skills/by default. - Consecutive hook commands with the same event, matcher, and timeout share a spec with a
command:list. - Fresh imports keep native command order with position prefixes in spec names. Keep those prefixes when renaming imported hooks.
- Import skips
version(always 1), aloop_limitof 0 (Trae treats it as unset), and the global~/.trae/hooks.json.