Strong framework with great docs and examples, but unfamiliar monorepo complexity and vague license designation will slow down newcomers.
last scored 2026-06-15
Readiness lenses
The same repo, two ways: how ready it is for an AI coding agent, and for a human newcomer. Switch lenses to see each one's score and checks.
How ready the repo is for an AI coding agent to read, build, and operate it.
27 of 35 checks passed across 6 categories.
Machine Orientation
7 checks passed1 problem found
- lowllms.txt present
An llms.txt is the emerging machine-orientation standard — a curated map for LLMs.
Fix: Add an llms.txt pointing at the key docs and entry points.
- README present — An agent reconstructs what the repo is and how to work in it from the README first.
- Agent instructions file — AGENTS.md / CLAUDE.md is the direct, machine-read channel for entry points and conventions.
- Agent instructions stay lean — A bloated instructions file burns context and measurably hurts more than it helps.
- Repository description set — The one-line description is the fastest orientation signal an agent reads.
- Topics set — GitHub topics situate the repo's domain and stack for an agent at a glance.
- Architecture doc — An ARCHITECTURE doc hands an agent the module map instead of making it infer one.
- Contribution conventions are written down — A contributor guide is where an agent learns the branch, commit, and review conventions it must follow.
Reproducible Setup
5 checks passed1 problem found
- lowDev container
A .devcontainer gives an agent a one-command, fully-declared environment.
Fix: Add a .devcontainer so the toolchain is declared, not assumed.
- Lockfile committed — Without a lockfile two clones can resolve different dependency trees — the build isn't reproducible.
- Runtime / toolchain pinned — An unpinned runtime makes an agent guess the version a clean environment needs.
- Version pins are exact — A floating pin (a bare major, or a range) still drifts between installs.
- Env template present — A .env.example tells an agent which configuration keys it must supply to run.
- Container or dev-container — A Dockerfile / compose / devcontainer removes 'works on my machine' from setup.
Code Navigability
2 checks passed0 problems found
- Conventional source layout — A recognised src/ · lib/ · app/ layout lets an agent localise code without spelunking.
- TypeScript strict mode on — Strict typing gives an agent typed signatures to anchor an edit on, not guesses.
Verification Surface
6 checks passed1 problem found
- lowTask runner present
A Makefile / Taskfile / justfile gives an agent a single index of the project's commands.
Fix: Add a Makefile / Taskfile / justfile collecting the common commands.
- Tests present — Runnable tests are the ground truth an agent checks its own edits against.
- Test command defined — A `test` script is the documented, discoverable way to run the suite.
- Lint command defined — A linter an agent can run catches a class of mistakes before they ship.
- CI configured — Readable CI is the feedback loop an agent reads to know what 'green' means here.
- Typecheck command — A typecheck script lets an agent catch type errors before they ship.
- Build command — A documented build command is the discoverable way for an agent to produce artifacts.
Agent Safety
5 checks passed3 problems found
- highNo committed .env
A tracked real .env hands secrets to anything — including an agent — that reads the repo.
Fix: Remove the .env from history, gitignore it, and ship a .env.example instead.
- mediumSecurity policy
A SECURITY.md is where an autonomous security agent reads this repo's rules before acting on it.
Fix: Add a SECURITY.md stating the disclosure channel and the repo's security rules.
- lowCODEOWNERS present
CODEOWNERS marks the 'don't touch without review' zones an agent should respect.
Fix: Add a CODEOWNERS file marking the sensitive paths.
- No exposed secrets — Secret-shaped literals in tracked files are a live credential leak.
- .gitignore covers env files — An ignore rule for .env is what keeps the next careless commit from leaking secrets.
- Automated dependency updates — Dependabot / Renovate keeps dependencies patched without a human in the loop.
- .gitignore present — A .gitignore is the first guard against an agent committing secrets or build junk.
- License makes the code reusable — Without a license an agent cannot safely copy, redistribute, or vendor any of this code.
Context Economy
2 checks passed2 problems found
- lowGenerated / vendored files marked
A .gitattributes linguist marker tells tools (and agents) what to skip.
Fix: Mark generated/vendored paths in .gitattributes (linguist-generated / linguist-vendored).
- lowNo oversized source file
A single file in the hundreds of KB blows past an agent's effective context window.
Fix: Split the largest files along their natural seams.
- Dependencies not vendored in — A committed node_modules / vendor tree drowns the real signal an agent needs.
- Build output not committed — Generated dist/ · build/ output is noise an agent has to read past.
How ready the repo is for a human newcomer to understand, set up, and contribute.
72 / 10020 of 25 checks passed across 6 categories.
First Impression
85Clear, well-decorated README with compelling feature highlights and multiple entry points for learning.
The README immediately explains what Mastra is (AI-powered apps framework for TypeScript), who it's for (developers building agents and workflows), and why it matters (handles model routing, agents, workflows, context management out-of-the-box). The quick-start command `npm create mastra@latest` is prominently placed, and links to docs, course, and YouTube videos lower friction. However, it lacks a visual demo or architecture diagram, leaving abstract what agents/workflows actually look like in practice.
Getting Running
68Quick-start CLI works, but monorepo development setup is opaque and dependency pinning is scattered across pnpm workspaces.
The README points to `npm create mastra@latest` (excellent for end-users) and references DEVELOPMENT.md for contribution setup, but the snapshot doesn't show DEVELOPMENT.md in full. The root package.json uses `catalog:` placeholders for deps (vitest, tsx, typescript, zod) pointing to a central version catalog, which is good for consistency but requires understanding pnpm workspaces. No pnpm-lock.yaml shown, making exact replication unclear. The 10k+ file tree with monorepo subdirs (packages/, integrations/, auth/, etc.) is intimidating without a clear entry point for local dev.
Finding Your Way
70Repository is modular and well-organized by function, but the sheer scale and interdependencies make mental mapping hard without explicit docs.
The file tree shows logical structure: packages/ (core, cli, server, mcp, evals, memory, rag), auth/, integrations/, deployers/, stores/, server-adapters/, workspaces/, client-sdks/. Each seems intentional, but with 10k+ files and no architecture overview or module dependency diagram visible in the snapshot, a newcomer must infer boundaries. The .claude/ and .cursor/ directories (AI-assistant configs) and dense .changeset/ directory clutter first-glance navigation. A DEVELOPMENT.md architecture section (referenced but not shown) likely exists, but should be more prominent.
Path to Contribute
80Thoughtful CONTRIBUTING.md with clear workflows, issue templates, and links to dev guide; beginner issues not explicitly surfaced.
CONTRIBUTING.md explicitly covers bug reports, PRs, features, and docs—with templates in .github/ISSUE_TEMPLATE/. It mandates linked issues for PRs (good guardrail) and mentions Coderabbit AI review feedback. The minimal reproduction guidance is practical. However, there's no 'good first issue' labeling visible, no explicit 'help wanted' board, and no separate guide for picking small wins. For first-timers, discovering where to start is still friction.
Signs of Life
78Active release cadence (changesets, alpha versioning, recent commits) and large star count signal health, but PR queue (409 open issues) hints at potential review lag.
The snapshot shows Last pushed: 2026-06-15 (recent, though this date appears to be a typo or edge case), 25k+ stars, dense changelog activity (many .changeset files), and CI/CD workflows (npm-publish, e2e-tests, alpha-publish). The .changeset/ folder with dozens of pending entries suggests active feature development. However, 409 open issues and the scale of the codebase suggest the maintainer team may be stretched, and newcomer PRs could face delays. The Discord link and active ecosystem (Y Combinator W25) suggest community, but responsiveness isn't directly verifiable.
Open Door
60License is dual-mode (Apache-2.0 core + Enterprise), clearly documented; lacks a Code of Conduct and formal security contact is present but no incident response SLA.
LICENSE.md maps Apache-2.0 for the core framework and Mastra Enterprise License for ee/ directories—this is transparent and well-explained in both README and CONTRIBUTING. A security@mastra.ai contact exists. However, a CODE_OF_CONDUCT.md is not mentioned in the snapshot, creating ambiguity about behavioral expectations. The dual-license structure, while legally sound, may confuse newcomers unsure which code is 'safe' to modify for production contributions. The enterprise license terms in ee/LICENSE are not shown, so enforceability and developer impact are opaque.
First Impression
3 checks passed0 problems found
- README present — The README is the first screen — with none, a newcomer has nothing to land on.
- Repository description set — The one-line description sets expectations before a newcomer even opens the README.
- Topics set — Topics situate the project's domain at a glance and help a newcomer find it.
Getting Running
5 checks passed1 problem found
- lowOne-click dev container
A .devcontainer lets a newcomer start in a cloud IDE with zero local setup.
Fix: Add a .devcontainer for a one-click, batteries-included environment.
- Lockfile committed — Without a lockfile a newcomer's install resolves differently and hits errors the docs don't mention.
- Prerequisite versions pinned — Unpinned prerequisites are the classic 'works on my machine' first-run failure.
- Env template present — A .env.example shows a newcomer exactly which settings they must fill in to run it.
- One-command environment — A Dockerfile / compose / devcontainer turns a fiddly setup into one command.
- Versions pinned exactly — A floating version still drifts — a newcomer can hit a break the maintainer never saw.
Finding Your Way
2 checks passed1 problem found
- lowNo oversized source file
A single thousand-line file is a wall a newcomer bounces off.
Fix: Split the largest files along their natural seams.
- Conventional source layout — A familiar src/ · lib/ · app/ layout lets a newcomer guess where things live.
- Architecture / overview doc — An overview hands a newcomer the map instead of making them reconstruct it.
Path to Contribute
5 checks passed1 problem found
- lowTask runner
A Makefile / Taskfile gives a contributor a single index of the project's commands.
Fix: Add a Makefile / Taskfile collecting the common dev commands.
- CONTRIBUTING guide — A CONTRIBUTING guide is the difference between a guessed and a guided first PR.
- Issue templates — Issue templates show a newcomer how to file something useful — and that contributions are welcome.
- Pull-request template — A PR template tells a first-time contributor what a good change includes.
- Test command defined — A documented test command lets a contributor check their change before opening a PR.
- Lint command — A linter lets a first-time contributor catch style issues before review.
Signs of Life
3 checks passed0 problems found
- Tests present — A test suite signals a project that's cared for, not abandoned.
- CI configured — Green CI on every change tells a newcomer the project is actively kept working.
- Automated dependency updates — Dependabot / Renovate activity is a visible heartbeat of ongoing maintenance.
Open Door
2 checks passed2 problems found
- lowLicense is a standard one
A non-standard or custom license is a legal question mark a newcomer won't resolve.
Fix: Use a recognised OSI license so reuse terms are unambiguous.
- lowSecurity policy
A SECURITY.md tells a newcomer how to report a problem responsibly.
Fix: Add a SECURITY.md describing how to report a vulnerability.
- License present — With no license the project isn't legally reusable — the door is shut however friendly the README.
- Code of conduct — A code of conduct states the social ground rules that make it safe to step in.
Where the grip slips
- highGetting Running+15 pts if fixed
Monorepo structure and dev setup are underdocumented, especially for first-time contributors
The snapshot references DEVELOPMENT.md but doesn't show it in full. Without visible guidance on which package to start with, how to run tests for a specific module, or how workspace dependencies resolve, newcomers won't know how to build and test their changes. The root package.json mentions `catalog:` for version pinning across pnpm, but this requires pnpm knowledge and isn't explained. The file tree shows 10k+ files with no README or ARCHITECTURE guide at the root.
Fix: Create or surface a DEVELOPMENT.md that includes: (1) quick command to run a single package in dev mode (e.g., `pnpm --filter @mastra/core dev`), (2) explanation of pnpm workspaces and catalog: version management, (3) a dependency graph or architecture diagram showing how packages relate, (4) clear 'start here' guidance for different contrib types (docs, core, integrations).
- highOpen Door+12 pts if fixed
License designation 'Other' on GitHub and confusing dual-license model may scare newcomers
The GitHub metadata lists License as 'Other', which is vague and doesn't point users to Apache-2.0 or the dual-license model. While LICENSE.md exists and is well-written, many newcomers won't dig into it. The distinction between Apache-2.0 code and Enterprise-licensed ee/ code is clear in the text, but the practical implication—what can a newcomer modify or deploy without buying a license—remains unclear. This ambiguity tanks trust and the 'open-door' score.
Fix: Update GitHub repo settings to identify the primary license as Apache-2.0 (not 'Other'). Add a prominent 'License' section to the top of the README that says: 'Mastra core is Apache-2.0 licensed. Some enterprise features (in `ee/` directories) are source-available under the Mastra Enterprise License for dev/test use; see [LICENSE.md](./LICENSE.md).' Also include a one-liner: 'Contributing to Apache-2.0 code is welcome; contributions to `ee/` require enterprise license agreement.'
- highFinding Your Way+12 pts if fixed
No architecture or module dependency diagram, making the 10k-file codebase feel impenetrable
The README highlights agents, workflows, model routing, and MCP servers, but doesn't explain how these fit together or which packages implement which features. A newcomer interested in 'contributing to agents' has no clear roadmap to packages/core/src/agents or wherever that code lives. The monorepo structure implies logical boundaries, but without a visual or textual guide, navigation is guesswork.
Fix: Add or surface an ARCHITECTURE.md with: (1) A dependency diagram (text or image) showing how packages/core feeds into packages/server, packages/cli, client-sdks/react, etc. (2) A feature-to-package map: 'Agents → packages/core/src/agents, Workflows → packages/core/src/workflows, etc.' (3) An entry point for each contrib type: 'To work on agents: start in packages/core, see packages/core/DEVELOPMENT.md.' Link this file prominently in the README under 'For Developers.'
- mediumPath To Contribute+10 pts if fixed
No beginner-friendly 'good first issue' labels or entry-point guidance in issues/discussions
While CONTRIBUTING.md is thorough, it doesn't surface how newcomers find low-hanging fruit. With 409 open issues and a complex codebase, a first-time contributor has no clear way to pick a starter task. Issue templates exist (.github/ISSUE_TEMPLATE/) but no mention of labels like 'good-first-issue' or 'help-wanted' to filter easy wins.
Fix: Adopt GitHub labels: 'good-first-issue', 'help-wanted', 'documentation'. Use GitHub's 'Contribute' tab to highlight these labels. Add a section to CONTRIBUTING.md: 'Getting started: Browse [good-first-issue](https://github.com/mastra-ai/mastra/labels/good-first-issue) to find tasks suited to newcomers.' Ensure maintainers tag issues consistently.
- mediumGetting Running+10 pts if fixed
pnpm workspaces and catalog: version management require undocumented knowledge
The root package.json uses `'catalog:'` as a version specifier for key dependencies (vitest, tsx, typescript, zod), which is a pnpm feature. Without a pnpm-lock.yaml in the snapshot or explanation of how to interpret catalog versions, a newcomer trying to add a dev dependency or pin a version will be confused. The DEVELOPMENT.md (not fully shown) likely covers this, but the snapshot itself provides no clue.
Fix: Add a section to DEVELOPMENT.md (or create pnpm-setup.md): 'This is a pnpm monorepo using a version catalog. To add/update a dependency: 1. Edit pnpm-workspace.yaml and .pnpmfile.cjs if needed. 2. For root dev deps, use pnpm add -D -w <pkg>; for package-scoped deps, pnpm add <pkg> -F <package-name>. 3. Run pnpm install to update pnpm-lock.yaml.' Include a link to the official pnpm workspaces guide.
- mediumOpen Door+8 pts if fixed
No visible Code of Conduct, weakening community safety signals
The snapshot shows no CODE_OF_CONDUCT.md, and the README emphasizes Discord community and security contact but not behavioral norms or incident response. For an AI-powered framework (which touches sensitive topics like model deployment), community trust is critical. The absence of a CoC suggests either it's hidden or not prioritized, both of which are red flags for newcomers assessing if this is a safe space to contribute.
Fix: Add a CODE_OF_CONDUCT.md (e.g., based on the Contributor Covenant or similar) and link it prominently in the README under a 'Community' section alongside the Discord link. Include a point of contact for CoC violations and a brief statement that the project is committed to a welcoming and inclusive environment.
- mediumFinding Your Way+8 pts if fixed
Confusing file tree with .claude/, .cursor/, and .changeset/ clutter obscures core structure on first visit
The snapshot shows 10k+ files, with prominent directories like .claude/ (AI assistant commands), .cursor/ (Cursor IDE configs), and .changeset/ (~50 pending change entries). These are internal/dev tools, not part of the shipped product, but they dominate the file tree view and confuse newcomers about what to explore first. The tree should foreground packages/, integrations/, etc.
Fix: Add a .gitattributes or .github/CODEOWNERS file that marks internal dirs (.claude/, .cursor/, .changeset/, .dev/, .github/) as 'linguist-documentation' or similar to de-emphasize them in GitHub's language breakdown. Create a root-level STRUCTURE.md that explains: 'Core framework is in packages/. Integrations in integrations/. Run `find . -maxdepth 1 -type d | grep -E '^\./[a-z]' | head -10` to see main dirs.' This sets expectations upfront.
Show your score
[](https://latch.fyi/mastra-ai/mastra)Share this analysis
https://latch.fyi/mastra-ai/mastraFixed some issues? Re-analyze to measure your progress →
Copy the whole report
Grab the entire verdict in one go — a Markdown block for a README or an issue, plain text, or a prompt you can paste straight into an LLM.