Project structure

Your new Mastra project, created with the create mastra command, comes with a predefined set of files and folders to help you get started.

Mastra is a framework, but it's mostly unopinionated about how you organize or colocate your files. The CLI provides a sensible default structure that works well for most projects, but you're free to adapt it to your workflow or team conventions. You could even build your entire project in a single file if you wanted! Whatever structure you choose, keep it consistent to ensure your code stays maintainable and straightforward to navigate.

Default project structure

A project created with the create mastra command looks like this:

src/
├── mastra/
│   ├── agents/
│   │   └── weather-agent.ts
│   ├── tools/
│   │   └── weather-tool.ts
│   ├── workflows/
│   │   └── weather-workflow.ts
│   ├── scorers/
│   │   └── weather-scorer.ts
│   └── index.ts
├── .env.example
├── package.json
└── tsconfig.json

Use the predefined files as templates. Duplicate and adapt them to quickly create your own agents, tools, workflows, etc.

Folders

Mastra recommends organizing your code into the following folders:

Folder	Description
src/mastra	Entry point for all Mastra-related code and configuration.
src/mastra/agents	Define and configure your agents - their behavior, goals, and tools.
src/mastra/workflows	Define multi-step workflows that orchestrate agents and tools together.
src/mastra/tools	Create reusable tools that your agents can call
src/mastra/mcp	Implement custom MCP servers to share your tools with external agents
src/mastra/scorers	Define scorers for evaluating agent performance over time

Mastra has two special folder conventions:

• src/mastra/agents/<name>: You can define an agent by file convention instead of constructing it in code. Learn more in the file-based agents guide.
• src/mastra/public: Contents are copied into the .build/output directory during the build process, making them available for serving at runtime.

Top-level files

Top-level files define how your Mastra project is configured, built, and connected to its environment.

File	Description
src/mastra/index.ts	Central entry point where you configure and initialize Mastra.
.env.example	Template for environment variables - copy and rename to .env to add your secret model provider keys.
package.json	Defines project metadata, dependencies, and available npm scripts.
tsconfig.json	Configures TypeScript options such as path aliases, compiler settings, and build output.