TraeCode Guide: How to Use TRAE for AI Coding, Agents, SOLO, Rules, MCP, and Real Projects

Key Takeaways

• TraeCode is TRAE's dedicated AI coding environment, combining a conventional IDE workflow with autonomous agent-based development.
• Its two core working styles are IDE mode for hands-on development and SOLO mode for AI-led planning, implementation, testing, and preview.
• TraeCode's AI stack extends beyond chat. It includes Agent, custom agents, CUE code assistance, workspace indexing, project rules, Skills, MCP, browser control, Hooks, and source-control integration.
• For existing repositories, context quality matters as much as model choice. Build the project index, exclude irrelevant files, and use #Workspace or #Folder deliberately.
• Projects with 5,000 files or fewer are automatically indexed when opened; larger repositories may need manual index creation for reliable project-wide retrieval.
• Durable development instructions should live in .trae/rules/, AGENTS.md, or other project configuration instead of being repeated in every conversation.
• TraeCode can be extended through custom agents, reusable Skills, MCP servers, and Hooks, making it more useful as an engineering workflow platform than as a simple code-completion tool.
• The safest workflow is still plan → inspect → branch → implement → test → review diff → commit. Autonomous coding reduces manual effort, but it does not remove the need for version control and verification.

TraeCode represents a broader shift in AI coding tools: instead of placing a chatbot beside a text editor, it attempts to connect AI directly to the development lifecycle.

That means understanding TraeCode requires more than learning where the prompt box is. Developers need to understand how project context is retrieved, when to use IDE or SOLO mode, how Agent differs from code completion, how rules influence behavior, how external tools are connected, and how to keep autonomous changes reviewable.

This guide covers that complete workflow.

What Is TraeCode?

TraeCode is an AI-integrated development environment designed for software development and engineering teams. It combines traditional IDE capabilities with agents that can inspect repositories, plan multi-step changes, edit files, run commands, test implementations, and help manage development work.

The key distinction is that TraeCode supports two different ways of working:

IDE mode
Developer controls the workflow
AI assists inside the normal coding environment

SOLO mode
AI drives more of the workflow
Agent plans, executes, tests, and presents results

This makes TraeCode useful for both developers who want AI assistance without giving up editor-level control and developers who want to delegate larger engineering tasks.

TraeCode vs the Older Trae IDE Name

Developers may still encounter names such as:

TRAE
TRAE IDE
Trae IDE
TraeCode

Current TRAE product positioning uses TraeCode for the dedicated coding environment, while TRAE itself is the broader product family.

Older articles and search results may therefore use Trae IDE when referring to substantially the same coding-product lineage.

For current guides, downloads, and feature documentation, TraeCode is the more useful term.

Who Should Use TraeCode?

TraeCode is most useful when AI needs to understand more than one isolated code snippet.

Strong use cases include:

• building a project from an initial specification
• understanding an unfamiliar repository
• implementing features across several files
• debugging cross-component issues
• refactoring existing systems
• generating and updating tests
• investigating runtime problems
• maintaining monorepos
• enforcing project conventions
• automating recurring development workflows
• connecting coding agents to external tools

It is less valuable when the task is simply editing a few lines of code that require no repository context or tool access.

How to Install TraeCode

TraeCode currently supports macOS, Windows, and several mainstream Linux environments. The official quick-start documentation lists macOS 12+, Windows 10/11 x64, Debian-family packages for supported Ubuntu and Debian releases, and RPM packages for supported Fedora and RHEL releases.

The basic installation workflow is:

1. Download the correct TraeCode package for the operating system.
2. Install and launch TraeCode.
3. Sign in when required.
4. Open a local project or clone a Git repository.
5. Allow the IDE to inspect and index the project.

Mac users should choose the build appropriate for Apple Silicon or Intel hardware.

Linux users should verify both package type and architecture before installation.

Start with an Existing Project

For an existing codebase, open the repository root rather than a deeply nested source directory.

Good:

my-app/
├── .git/
├── src/
├── tests/
├── package.json
├── README.md
└── tsconfig.json

Less useful:

my-app/src/components/dashboard/

Opening the actual root gives TraeCode access to configuration, tests, dependencies, documentation, Git metadata, and related modules.

TraeCode also supports cloning repositories through GitHub authorization or by supplying a repository URL.

Before asking an agent to modify anything, check the repository state:

git status
git branch --show-current

A clean working tree provides a reliable baseline for reviewing AI-generated changes.

IDE Mode vs SOLO Mode

Understanding this distinction is central to using TraeCode effectively.

IDE mode preserves the familiar development workflow. The developer navigates files, edits code, runs commands, uses source control, and decides how much responsibility to delegate.

Use IDE mode when:

• modifying production code carefully
• debugging an existing system
• reviewing individual changes
• working with sensitive repositories
• making small or medium changes
• learning an unfamiliar codebase

SOLO mode is more agent-driven. TraeCode can interpret a natural-language objective, plan the work, modify the codebase, run tools, test the result, and provide a preview or summary.

Use SOLO when:

• implementing a complete feature
• generating a prototype
• performing a structured refactor
• executing a well-defined multi-step task
• delegating work that spans several parts of a repository

A productive workflow often uses both modes rather than choosing one permanently.

For example:

IDE mode → inspect architecture
SOLO → implement feature
IDE mode → review diff
SOLO → fix test failures
IDE mode → final verification and commit

Use Agent for Multi-Step Engineering Tasks

TraeCode's built-in Agent is designed for development work that requires more than answering a question.

It can investigate the repository, identify relevant files, construct an implementation plan, make changes, invoke tools, validate results, and involve other agents when appropriate.

A strong Agent prompt looks like:

Add email verification to the existing authentication flow.

Requirements:
- preserve password login
- reuse the existing mail service
- add database changes only if necessary
- include tests for expired and invalid verification tokens
- do not introduce another authentication library

First inspect the current authentication architecture and provide a plan before modifying files.

A weak prompt is:

Improve auth.

The difference is not verbosity for its own sake. The stronger prompt defines outcome, boundaries, reuse requirements, validation, and execution order.

Use CUE for Fast Interactive Coding

Not every task needs an autonomous Agent.

TraeCode includes CUE, its coding-assistance layer for faster interactive editing. Current documentation describes capabilities including code completion, multi-line modification, modification prediction, smart imports, and intelligent rename behavior.

CUE is best suited to short feedback loops such as:

• completing functions
• extending repetitive logic
• editing nearby code
• adding imports
• renaming references
• predicting the next change

A useful mental model is:

CUE = accelerate what the developer is already editing
Agent = execute a larger engineering objective

Using Agent for every trivial change introduces unnecessary overhead. Conversely, expecting completion alone to perform architecture-level work undersells what the agent system can do.

Choose the Right Model for the Task

TraeCode supports multiple built-in models and also allows custom model configuration. Model capabilities vary, so the best model for fast completion may not be the best model for complex repository reasoning or visual input.

Model selection should be based on task characteristics:

Avoid assuming that the largest or most expensive model should handle every task.

A good workflow routes simple tasks to faster models and reserves heavier reasoning for changes where errors would be expensive.

Understand TraeCode Context

AI coding quality depends heavily on context.

There are three different problems a developer must solve:

What does the model know generally?
What does the model know about this repository?
What information is relevant to this specific task?

TraeCode addresses repository context through workspace indexing and context references such as #Workspace and #Folder.

Use narrow context when possible.

For example:

selected code → one implementation detail
file → one module
#Folder → one subsystem
#Workspace → architecture or cross-project reasoning

More context is not automatically better. Irrelevant files consume retrieval capacity and increase the chance that the agent follows the wrong implementation pattern.

Build the Workspace Index

TraeCode's workspace index is one of the most important features to configure correctly for existing repositories.

When an index exists, project-level requests using #Workspace or #Folder can retrieve relevant code across files. Incomplete indexing can produce incomplete repository understanding.

Current documentation states that projects containing 5,000 files or fewer are automatically indexed when opened. For projects above that size, manual indexing may be necessary when accurate project-level retrieval is required.

This threshold makes ignore configuration especially important in JavaScript monorepos and generated-code-heavy projects.

Exclude Noise from AI Context

An index should contain useful source context, not every byte in the repository.

Typical candidates for exclusion include:

node_modules/
dist/
build/
.next/
coverage/
.tmp/
generated/
large binary assets
local data exports
secret files

TraeCode's context settings allow ignore rules to supplement .gitignore, and ignored content is excluded from the code index.

This has two benefits:

• better retrieval quality because generated noise is removed
• better data hygiene because unnecessary sensitive files are kept out of project retrieval

Use Project Rules for Persistent Instructions

Repeatedly typing the same architecture rules into AI prompts is inefficient.

TraeCode supports global rules and project rules. Project-specific rules are stored under:

.trae/rules/

Global rules apply across projects, while project rules apply to the current repository.

Good rule candidates include:

• coding style
• allowed dependencies
• architecture boundaries
• test requirements
• naming conventions
• error-handling patterns
• database rules
• security constraints
• commit-message format

For example:

---
alwaysApply: true
---

- Use TypeScript strict mode.
- Reuse existing API clients before creating new ones.
- Do not edit generated files.
- Add tests for behavior changes.
- Never expose server credentials to client-side code.

Rules are most useful when they contain durable engineering constraints rather than task-specific instructions.

Use AGENTS.md and CLAUDE.md When Appropriate

TraeCode can incorporate repository instructions from AGENTS.md, CLAUDE.md, and CLAUDE.local.md when the relevant import options are enabled.

This is useful for teams using several coding agents.

A practical division is:

README.md
Human-oriented project introduction

AGENTS.md
Portable instructions for coding agents

.trae/rules/
TraeCode-specific rules

 docs/
Detailed architecture and product documentation

Avoid duplicating hundreds of lines of identical instructions across every agent configuration. A smaller shared source of truth is easier to maintain.

Create Custom Agents for Specialized Work

TraeCode allows developers to create custom agents and configure their prompts, tools, and MCP access.

This is useful when one repository repeatedly requires specialized roles such as:

• frontend implementation
• test generation
• security review
• database migration review
• API design
• accessibility auditing
• performance optimization

Instead of repeatedly writing:

Act as an experienced security reviewer and check...

create a security-focused agent with stable instructions and tools.

The built-in Agent can also work with sub-agents for more complex tasks.

This allows an engineering workflow to evolve from one general-purpose assistant into several specialized agents.

Think of Multi-Agent Work as Engineering Delegation

The useful way to approach multiple agents is not to maximize the number of agents.

Instead, divide work where specialization improves quality.

For example:

Main Agent
├── Requirements Agent
├── Backend Agent
├── Frontend Agent
├── Test Agent
└── Security Review Agent

A complex feature can then follow this flow:

requirements
→ architecture
→ implementation
→ testing
→ security review
→ final integration

For a small component fix, this structure would be unnecessary. Multi-agent orchestration should solve complexity, not create it.

Use Skills for Reusable Workflows

TraeCode supports Skills, reusable capability packages defined through SKILL.md files. A Skill can contain instructions, scripts, supporting files, examples, and a description explaining when the agent should use it.

Project Skills can live under paths such as:

.trae/skills/code-review/SKILL.md

TraeCode also supports the .agents/skills/ convention used by the broader Agent Skills ecosystem.

A Skill is a better fit than a normal rule when the content describes how to perform a repeatable workflow.

Examples:

Rule:
All API errors must use the project's standard error shape.

Skill:
How to perform a release-readiness audit across tests, migrations,
configuration, changelog, and deployment files.

Rules constrain behavior. Skills package reusable expertise.

Connect External Tools with MCP

TraeCode supports Model Context Protocol servers, allowing agents to use external tools and services. MCP servers can be added from the built-in marketplace or configured manually.

Potential MCP use cases include:

• documentation retrieval
• database tooling
• issue tracking
• browser automation
• internal engineering systems
• deployment tooling
• specialized search

A simplified architecture looks like:

TraeCode Agent
      ↓
     MCP
      ↓
External tool or service

For locally executed MCP packages, the required runtime must exist on the machine. TraeCode's documentation notes that marketplace entries using local execution may require tools such as NPX or UVX.

Treat MCP access like any other powerful developer integration: grant only the permissions necessary for the task.

Use Browser Control for UI Verification

TraeCode supports browser control so AI can open pages, inspect content, interact with interfaces, and help verify web applications. Both an internal browser workflow and external Chrome-based interaction are supported depending on configuration.

Useful cases include:

• opening a local development server
• testing a form
• checking a responsive layout
• verifying text after implementation
• reproducing a browser-visible bug
• validating a feature after an agent modifies the code

A useful request is:

Start the application, open the checkout page, verify the mobile layout at 390px width, and check that the order summary no longer overflows.

One important limitation in current documentation is that the Chat agent itself cannot operate the browser, so use an appropriate agent workflow when browser actions are required.

Use Multimodal Input for Visual Development

Visual tasks are often easier to communicate with an image than with several paragraphs of prose.

Useful visual inputs include:

• screenshots
• error states
• UI mockups
• design references
• architecture diagrams
• responsive examples

A strong multimodal request combines the image with code context:

The attached screenshot is the target desktop layout.

Inspect the existing PricingPage and PricingCard components.
Match the layout hierarchy, card proportions, spacing, and responsive structure.

Preserve:
- existing pricing data
- current button component
- accessibility behavior

Do not install another UI library.

The image explains what the result should look like. The repository explains how the product currently works. The text prompt defines what the AI is allowed to change.

Use Git as the Safety Boundary

AI agents can make large changes quickly. That makes source control more important, not less important.

TraeCode includes source-control support for commits, branches, remotes, and AI-generated commit messages.

Before a substantial task:

git status
git switch -c feature/account-settings

After the agent works:

git diff
git status

Then run tests before committing.

Never treat an AI-generated summary as a substitute for reviewing the diff.

Use AI-Generated Commit Messages Carefully

TraeCode can generate commit-message drafts from repository changes.

This is convenient, but the generated message should describe the actual diff rather than the original prompt.

For teams using structured commits, project rules can also define Git commit-message requirements.

For example:

feat(auth): add email verification flow
fix(cart): prevent duplicate checkout submission
refactor(api): centralize request validation

Automating the wording is useful. Automating the decision about what belongs in a commit is more risky.

Use Hooks to Automate Guardrails

TraeCode Hooks allow custom shell commands to run at specific points during agent execution.

Current documentation includes events around session startup, prompt submission, tool use, and task completion. Hooks can inject context, validate tool actions, record logs, run checks, or block unsafe operations.

This enables workflows such as:

Agent wants to edit files
→ PreToolUse Hook checks protected paths
→ edit is allowed or rejected

Agent says task is complete
→ Stop Hook runs test suite
→ failure prevents premature completion

Project Hook configuration can live under:

.trae/hooks.json

while global Hook configuration can apply across workspaces.

Hooks are particularly valuable for teams that need deterministic controls around probabilistic AI behavior.

A Practical Hook Strategy

Start with validation rather than building an elaborate automation framework immediately.

High-value examples include:

• block modifications to generated files
• prevent edits to protected configuration
• run formatting after code generation
• run tests before task completion
• run a security scanner after dependency changes
• inject environment-specific context at session startup

The best Hooks are small, deterministic, and easy to debug.

Manage Permissions Conservatively

Agentic development becomes risky when every action is automatically approved.

Potentially sensitive actions include:

• deleting files
• running shell commands
• modifying infrastructure
• changing dependencies
• accessing external services
• editing deployment configuration
• touching credentials

For exploratory work, grant only the permissions needed for the current task.

For established automated workflows, broader permissions become more reasonable after the repository has strong Git discipline, tests, Hooks, and protected paths.

A Strong TraeCode Workflow for Existing Repositories

Use the following process for serious development work.

Step 1: Open the correct repository root.

Make sure configuration, tests, source code, documentation, and Git metadata are visible.

Step 2: Check source control.

git status
git branch --show-current

Step 3: Check indexing.

Make sure repository-wide context is available before asking architecture-level questions.

Step 4: Configure rules.

Add project conventions that should survive across conversations.

Step 5: Ask Agent to map the feature.

Use project context to trace the checkout flow from the UI to payment creation and webhook processing.

List the important files, data boundaries, and existing tests.
Do not edit anything.

Step 6: Create a branch.

git switch -c feature/checkout-retry

Step 7: Give one concrete implementation objective.

Add idempotent retry handling for payment creation using the existing payment service.

Preserve the public API.
Add tests for duplicate submissions and timeout retries.
Do not introduce another payment library.

Step 8: Let the agent implement and test.

Step 9: Review the actual diff.

git diff

Step 10: Run the project's tests independently.

npm test

Use the repository's real command where different.

Step 11: Commit one coherent change.

This process keeps autonomous development fast without sacrificing reversibility.

A Strong TraeCode Workflow for New Projects

For greenfield development, begin with product constraints rather than immediately generating files.

A useful first prompt is:

Build a lightweight SaaS dashboard for managing API usage.

Stack:
- React
- TypeScript
- Tailwind CSS
- existing project package manager

Core features:
- authentication
- API key management
- usage dashboard
- billing page

Requirements:
- mobile responsive
- accessible forms
- no unnecessary dependencies
- clear separation between UI and API logic

First propose the architecture, routes, data model, and implementation milestones. Do not generate code yet.

After reviewing the architecture, instruct Agent to build milestone by milestone.

This is more reliable than asking for the entire application in one uncontrolled step.

Prompting TraeCode Effectively

The most reliable prompts contain six elements:

1. Outcome
2. Context
3. Constraints
4. Scope
5. Verification
6. Execution order

For example:

Outcome:
Add CSV export to the analytics page.

Context:
Use the existing analytics query and filtering logic.

Constraints:
Do not add another CSV dependency unless native implementation is impractical.
Preserve the current API.

Scope:
Analytics page and directly related utility files only.

Verification:
Add tests for escaping commas, quotes, and newlines.

Execution:
Inspect the existing implementation and show the plan before editing.

This reduces the amount of judgment the model must invent independently.

Avoid Over-Prompting

More instructions are not always better.

A 2,000-word prompt containing conflicting details can produce worse results than a concise specification.

Use persistent rules for stable requirements and keep each task prompt focused on the current outcome.

A useful separation is:

Project rules → permanent engineering constraints
Documentation → architecture and domain knowledge
Prompt → current task
Agent plan → execution strategy

Common Mistake: Using #Workspace for Everything

Repository-wide context is powerful but expensive and noisy.

For a one-file problem, use the relevant file or selection.

For one subsystem, use #Folder.

Reserve broad workspace retrieval for questions that genuinely cross multiple modules.

The goal is not maximum context. The goal is maximum relevant context.

Common Mistake: Starting Large Changes Before Indexing Completes

If project-level indexing is incomplete, the AI can miss existing abstractions and produce duplicate implementations.

Typical symptoms include:

• creating utilities that already exist
• missing an important service layer
• changing only one side of an integration
• misunderstanding dependency relationships

For repository-wide work, verify indexing first.

Common Mistake: Putting Secrets in AI Context

Repository context can contain sensitive material.

Keep unnecessary secrets out of indexed files and prompts, including:

• production API keys
• private keys
• authentication tokens
• database passwords
• customer data
• cloud credentials

Use environment-variable templates and secret-management systems instead.

Common Mistake: Treating Agent Output as a Finished Code Review

An agent may successfully implement a feature while still producing:

• unnecessary dependencies
• duplicated abstractions
• weak error handling
• missing edge cases
• overly broad edits
• incomplete tests

Review the diff from the perspective of maintainability, not merely whether the feature appears to work.

Common Mistake: One Massive Autonomous Task

Requests such as:

Rewrite this entire app and make everything better.

create poor review boundaries.

A better sequence is:

1. map current architecture
2. identify technical problems
3. rank changes by impact
4. create migration plan
5. implement one subsystem
6. verify tests
7. continue to next subsystem

AI coding works best when individual milestones have observable success criteria.

Common Mistake: Creating Too Many Custom Agents

Custom agents are useful, but each additional agent adds configuration and coordination overhead.

Create a specialized agent only when the task occurs repeatedly or genuinely benefits from distinct tools and instructions.

A project rarely needs 20 agents on day one.

Start with Agent plus one or two specialists, then expand when repeated patterns emerge.

Common Mistake: Installing Too Many MCP Servers

Every external integration increases attack surface, maintenance cost, and potential context noise.

Before adding an MCP server, ask:

• What specific task does it solve?
• What permissions does it need?
• Could a built-in tool already do the job?
• Does it expose sensitive information?
• Is it maintained?

Treat agent integrations with the same caution as development dependencies.

Common Mistake: Confusing TraeCode with TraeCode CLI

TraeCode CLI is a separate terminal-based coding agent. Current documentation describes TraeCode CLI 2.0 as capable of understanding repositories, modifying workspace files, executing commands, generating and reviewing code, and extending behavior through plugins, Skills, MCP, and ACP.

Choose TraeCode desktop when you want:

• graphical editing
• integrated project navigation
• visual source control
• IDE and SOLO switching
• browser and preview workflows

Choose TraeCode CLI when you prefer:

• terminal-first development
• automation
• scripts
• remote shells
• non-interactive runs
• CI-oriented workflows

Many advanced developers can benefit from using both.

TraeCode Feature Map

The central insight is that these features solve different problems. Effective TraeCode usage comes from combining them deliberately rather than turning everything on at once.

Recommended TraeCode Setup for a Serious Project

A practical repository might evolve toward this structure:

my-project/
├── .trae/
│   ├── rules/
│   │   ├── general.md
│   │   ├── frontend.md
│   │   └── testing.md
│   ├── skills/
│   │   └── release-review/
│   │       └── SKILL.md
│   └── hooks.json
├── src/
├── tests/
├── docs/
├── AGENTS.md
├── README.md
└── package.json

Each part has a distinct responsibility:

rules → constraints
skills → repeatable expertise
hooks → deterministic automation
AGENTS.md → shared agent guidance
docs → architecture knowledge
source/tests → implementation and verification

That separation makes AI behavior easier to understand and maintain.

Advanced Strategy: Turn TraeCode into a Development System

The largest productivity gains come when TraeCode is treated as a workflow platform instead of an isolated assistant.

A mature development loop can look like:

User requirement
      ↓
Agent planning
      ↓
Workspace retrieval
      ↓
Project rules
      ↓
Specialized Skill / Subagent
      ↓
MCP or development tools
      ↓
Code changes
      ↓
Hook validation
      ↓
Browser or automated tests
      ↓
Git diff review
      ↓
Commit

Each layer reduces a different type of failure.

• Indexing reduces missing context.
• Rules reduce inconsistent implementation.
• Skills reduce repeated procedural prompting.
• Specialized agents improve division of labor.
• MCP extends tool access.
• Hooks introduce deterministic controls.
• Git preserves reversibility.
• Tests provide evidence that the implementation works.

This is a more robust model than simply asking a chatbot to generate code.

Is TraeCode Worth Learning?

TraeCode is most compelling for developers who want AI to operate at the repository and workflow level, rather than only generate isolated code snippets.

Its value increases with task complexity because features such as indexing, Agent, SOLO, rules, Skills, MCP, browser control, source control, and Hooks become more useful when changes span several files or systems.

The learning curve is therefore less about memorizing keyboard shortcuts and more about learning how much autonomy to give the AI, what context to provide, and how to build reliable verification boundaries.

For simple coding assistance, CUE and IDE mode may be enough.

For complex product work, Agent and SOLO become more important.

For repeatable team workflows, rules, Skills, MCP, Hooks, and specialized agents provide the deeper leverage.

Conclusion

TraeCode is best understood as an AI-native engineering environment, not merely another editor with autocomplete.

Its traditional IDE mode provides developer control, while SOLO and Agent enable increasingly autonomous development. Workspace indexing gives AI repository awareness; rules preserve engineering standards; Skills package reusable workflows; MCP connects external services; Hooks add deterministic automation; and Git provides the safety boundary required for fast AI-generated changes.

The best way to learn TraeCode is not to enable every advanced feature immediately. Start with one real repository, build the code index, create a few concise project rules, use Agent for a small feature, inspect the diff, and verify the result with tests.

Then progressively add Skills, custom agents, MCP, browser verification, and Hooks where they solve recurring problems.

The goal is not maximum automation. The goal is a development workflow where AI can move quickly while context, rules, tests, and source control keep the work understandable and reversible.