Trae

Vendor: ByteDance Install name: trae Status: GA Native config: <project>/.trae/rules/apothem-rules.md

InstallationCopy Anchor Link

apothem install --harness trae --project /path/to/project

The adapter writes one project-scope Trae rules file from the shared Apothem rules and governance surface, and Apothem's helpers as Trae subagents in the project (see Subagents).

It also writes Apothem's skills, and the rules and templates they cite, to your user home, before it touches the project (see Files outside the project).

Files written:

• <project>/.trae/rules/apothem-rules.md, the rules file.
• <project>/.trae/agents/<name>.md for each Apothem helper, in the project.
• ~/.trae/skills/<name>/SKILL.md for each Apothem skill and command, in your user home.
• ~/.config/apothem/rules/ and ~/.config/apothem/templates/, in your user home.

Files outside the projectCopy Anchor Link

The install also writes Apothem's skills to your user home, before it changes anything in the project:

These folders are shared. They are not private to the project:

• Every project you install trae into uses the same copy of ~/.trae/skills/, and the install writes the same files into it each time. Trae is the only tool that reads that folder. The rules and templates under ~/.config/apothem/ are written by the other tools' installs as well, with the same files.
• --project chooses the rules file to write and which project the install belongs to. It does not change where the skills go.
• The install adds no skill or rule file to your repository. The project gets the rules file and the subagent files in .trae/agents/, plus the .apothem/ data folder every project install creates.
• The home folders are written first. If that fails, for example because a folder in the path is a link that leaves your home directory (a link that stays inside it is followed) or cannot be written, the install stops with the error before anything in the project changes.
• A skill folder with an Apothem skill's name that Apothem did not write is left alone, and the install prints a warning that names it. Rename or move it, then run apothem update. apothem verify fails while that name is held.
• The files add up to a few megabytes.

The install prints a note that names the folders it writes outside --project, and --dry-run lists them.

SubagentsCopy Anchor Link

Trae reads a subagent from a Markdown file in <project>/.trae/agents/, per the Trae subagents documentation. The install writes one file per Apothem helper into that folder. It installs for the project only: the documentation gives the user-level folder as ~/.trae-cn/agents/ while every other Trae user folder is under ~/.trae/, and Apothem has not confirmed which one an international install reads, so it writes neither.

Each file keeps the helper's instructions unchanged and carries these frontmatter keys:

Only the tool names on Trae's subagents page are written:

Bash, Edit, Glob, Grep, Read, Skill, TodoWrite, WebFetch, WebSearch, Write, LSP

A tool the source names that is not in that list (for example MultiEdit or PowerShell) is left out of both fields. A tool with a pattern, such as Bash(rm *), has no form in a comma list: as an allowed tool it is left out, and as a denied tool it denies the whole tool. A helper that cannot edit files keeps that limit: it lists no Write or Edit among its tools and denies both. Trae documents no turn limit, so the helper's maxTurns is not written. The install writes no model key, so a helper uses the model chosen in the chat box, and no mcpServers key.

Things to know:

• Trae's English documentation says to turn on Settings > Beta > Subagents > Enable Subagents Directory before it loads .trae/agents/. Its Chinese page, updated later, says the feature is usually on by default. If Trae lists none of the helpers, check that switch.
• The subagent files are ordinary project files. Commit them with the project or list .trae/agents/ in .gitignore; Apothem does not choose for you.
• A file of yours with an Apothem helper's name is saved under ~/.apothem/backups/ and then replaced. The uninstall does not put it back. Files with other names are never touched.
• Trae's documentation does not say how it treats a frontmatter key it does not list, or whether .trae/agents/ applies in the second window of the merged "all-new TRAE" as it does in the IDE window.

Profile-to-native-config mappingCopy Anchor Link

The adapter reads Apothem's shared profile and renders the project rules file on every apothem install or apothem update run. The shared profile is the source of truth; project-local edits to the generated file are backed up before the next sync replaces the Apothem-managed content.

The file opens with YAML frontmatter that sets alwaysApply: true and a description, which is Trae's Always Apply mode per the Trae rules documentation. The Apothem-managed block follows it; text you add after the block is kept on every sync.

Compatibility notesCopy Anchor Link

Trae's current rules surface is project-scoped under .trae/rules/; global rules live under ~/.trae/user_rules. The adapter writes a dedicated apothem-rules.md file and never clobbers the other rule files in that directory or your global rules. The .trae/mcp.json tool-server surface and the project .trae/skills/ skill surface are operator-owned; Apothem does not write them.

Trae documents ~/.trae/skills/ for global skills. It reads the cross-tool .agents/skills/ folder only after the setting Enable .agents Skills Directory is switched on, so the install writes the Trae folder. The China edition (TRAE CN) documents ~/.trae-cn/skills/ instead; its changelog says the global skills directories of TRAE CN and the international edition are compatible, for the personal edition only. The install writes ~/.trae/skills/ only, and Apothem has not confirmed whether the other TRAE CN editions read it. Apothem has also not confirmed how Trae treats a SKILL.md header key it does not list.

VerificationCopy Anchor Link

apothem verify --harness trae --project /path/to/project

The verify command confirms that:

1. The native config exists at the expected path.
2. Each managed target exists, the .trae/agents/ folder included; managed files are non-empty, and JSON or YAML configs parse. Add --profile PATH to also confirm that the installed files match that profile. For .trae/agents/ the check is that the folder exists, not that each helper file is in it; the command apothem diff --harness trae --project /path/to/project lists the helper files that are missing or out of date.
3. Every Apothem skill folder is in place with a SKILL.md, whichever install wrote it, and no skill folder with an Apothem name belongs to something Apothem did not write. A failed check names the missing or foreign folders.
4. The adapter-specific verification routine reports success.

UpdatingCopy Anchor Link

apothem update --harness trae --project /path/to/project

Re-derives the project rules file from the current shared profile state.

The update also rewrites any skill folder whose files differ from the current ones. If you installed with an earlier release that wrote no skills, the update adds them. It rewrites subagent files that differ from the current ones, and adds any that are missing.

UninstallingCopy Anchor Link

apothem uninstall --harness trae --project /path/to/project

Removes the Apothem block, and the frontmatter Apothem wrote above it, from <project>/.trae/rules/apothem-rules.md and keeps any other text in it. The file is deleted only when nothing else remains in it. Before the change, a timestamped copy of the file is saved under ~/.apothem/backups/; no backup file is left in the project. The shared profile YAML and Apothem engine are unaffected.

The uninstall also removes the subagent files it wrote in <project>/.trae/agents/ and keeps any other file there; the folder is removed when it is left empty. It removes the skill folders it wrote in ~/.trae/skills/ and the rules and templates in ~/.config/apothem/, but only when no other Apothem install still uses them. Another project, or another tool that shares the folder, may. In that case the uninstall keeps the folders, prints which install uses them, and the last uninstall removes them. Files you added to those folders stay, and a folder left empty is removed. Each folder is backed up under ~/.apothem/backups/ before it is removed.

Conformity gateCopy Anchor Link

python -m apothem.conformity.gate --all .

TroubleshootingCopy Anchor Link

Configuration knobsCopy Anchor Link

See alsoCopy Anchor Link

• All harnesses — the full catalog of supported tools
• Install guide — install Apothem into this harness
• apothem harnesses reference — list and inspect adapters from the CLI