> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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:

```bash
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](https://mastra.ai/docs/getting-started/file-based-agents) docs.
- `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](https://mastra.ai/models) 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.                                           |