Better Agents: a scaffolder that writes your agent project's test, eval and prompt layout
Standards for building agents, better
At a glance
- What is it?
- langwatch/better-agents is an MIT-licensed TypeScript CLI that generates a fixed directory structure plus an AGENTS.md file, then wires your coding assistant to framework-specific MCP servers. The value is the layout, not the generated agent code, and the layout assumes you accept Scenario tests and LangWatch prompt syncing.
- Who is it for?
- Adopt Better Agents if you are starting a new agent project in Agno, Mastra or LangGraph, you already use a supported coding assistant, and you are willing to keep prompts in YAML under prompts/ synced through prompts.json. Do not adopt it to retrofit an existing repository, to work in a framework the CLI does not offer, or if a LangWatch API key and the Scenario test dependency are unacceptable.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 104 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is project layout, not agent code
Most agent repositories start as a single script that calls a model, and the structure around it gets added later or never. Prompts live inline in Python or TypeScript strings, so nobody can diff them. There is no test that fails when the agent stops behaving, only unit tests for helper functions. Evaluation work happens in a notebook that someone ran once. Better Agents targets that gap by generating the surrounding structure before the first feature is written. The README frames it as a CLI tool and a set of standards, and the standards part is the substance: a directory tree, an AGENTS.md file that tells a coding assistant how to work inside it, and a .mcp.json that points that assistant at framework documentation. The audience is a developer or small team starting a greenfield agent in Agno, Mastra or LangGraph who wants the testing and prompt-versioning conventions decided up front rather than negotiated later.
What init actually generates, directory by directory
The README prints the full tree. app/ (or src/, depending on language) holds the agent code in whatever framework you picked. tests/ splits into evaluations/, containing Jupyter notebooks such as example_eval.ipynb, and scenarios/, containing end-to-end tests named example_scenario.test.py or .test.ts. prompts/ holds versioned prompt files in YAML, with sample_prompt.yaml as the starting example, and prompts.json acts as the registry that controls them. Alongside those sit .mcp.json for MCP server configuration, AGENTS.md for development guidelines, .env and .gitignore. The claim that matters is the coupling: the README states the structure and AGENTS.md guidelines together ensure that every new feature is properly tested, evaluated and has versioned prompts. That is a convention enforced by a document a coding assistant reads, not by a linter or a build step. Nothing in the material describes a runtime component that rejects a commit which skips tests/scenarios, so treat the enforcement as social plus assistant-mediated.
MCP configuration is how the assistant learns your framework
The mechanism for framework expertise is .mcp.json. The README says it comes with the right MCPs set up so the coding assistant becomes an expert in your chosen framework and in writing Scenario tests. That is a different approach from shipping a plugin or a rules file per framework: the assistant queries MCP servers at generation time instead of relying on training data. The practical consequence is that the quality of generated agent code depends on those servers being reachable and current, and on your assistant supporting MCP at all. Of the four assistants listed in Requirements, Claude Code, Cursor, Antigravity and Kilocode CLI, the README does not break down which MCP features each one exposes. If your assistant is not on that list, the .mcp.json file is inert and you are left with the directory structure and AGENTS.md only, which is still usable but is a smaller product than advertised.
Installing and running the initializer
Installation is a global npm package: npm install -g @langwatch/better-agents. The README also gives npx @langwatch/better-agents init my-agent-project for a one-off run. Once installed, better-agents init . scaffolds into the current directory and better-agents init my-awesome-agent creates a new one. The CLI is interactive: the README states it guides you through selecting programming language, agent framework, coding assistant, LLM provider and API keys. Requirements are Node.js 22 or newer, npm or pnpm, one of the four named coding assistants, a LangWatch API key from https://app.langwatch.ai/authorize, and an LLM provider key. Anonymous telemetry is on by default; set BETTER_AGENTS_TELEMETRY=0 to turn it off. The LangWatch key is the detail worth pausing on. Prompt syncing through prompts.json and the evaluation notebooks both point at LangWatch infrastructure, so the scaffold is not fully standalone even though the CLI itself is MIT-licensed.
The Scenario test dependency is the real constraint
Scenario tests are the part of the structure with the most opinion behind it. The README describes them as simulating a conversation with the agent to check it does what is expected, and links to a separate repository, langwatch/scenario. That means your generated project's test suite depends on a second project with its own release cadence, its own bugs and its own upgrade path, and the version you get is whatever the CLI pins at generation time. The README does not state how Scenario tests are executed in CI, whether they need network access to a model provider on every run, or what they cost per run. Those are the questions to answer before you commit to the layout, because a scenario test that calls a live model is a different operational object from a unit test. The generated example is a single file, example_scenario.test.py or .test.ts, so the pattern is demonstrated rather than proven at scale.
Prompt versioning via YAML and prompts.json
Prompts live as YAML files under prompts/, with prompts.json as the registry, and the README ties this to playground and team collaboration through the LangWatch prompt management CLI. The design choice here is that prompts are data files separate from code, which makes them reviewable in a pull request and editable by someone who does not want to touch the agent source. The cost is a sync step: prompts.json and the YAML files have to stay consistent, and the README does not document what happens when they drift, nor whether the CLI validates the registry. If your team already keeps prompts in a database or a feature-flag service, this directory is a second source of truth and you should decide which one wins before the first prompt is edited in two places.
Where this is the wrong tool
Better Agents generates a new project. There is no documented migration path for an existing repository, and running init against a directory that already has app/ and tests/ is not described in the README, so the safe assumption is that it is a greenfield-only tool. The framework list in the README is Agno, Mastra and LangGraph; if you are on a framework outside it, the .mcp.json servers will not match your stack and the generated app/ will not be useful. The assistant list is equally narrow. And the eval notebooks are Jupyter, which sits awkwardly in a TypeScript-first project: the README's own tree shows example_eval.ipynb next to a .test.ts scenario file, so a TypeScript team ends up maintaining a Python notebook toolchain for evaluations. None of these are defects exactly, but each one is a reason the scaffold might not fit.
Compared with a plain template repository
The obvious alternative is a GitHub template repository or a cookiecutter-style generator that copies a directory and stops. The difference is what happens after generation. A template gives you files and no ongoing relationship with your coding assistant; Better Agents additionally writes AGENTS.md and .mcp.json so the assistant that writes your next feature has framework documentation and testing conventions in context. That is the whole bet: the generated structure is only as good as the assistant's adherence to it. The counter-argument is that a template repository is inspectable before you copy it, whereas here the output depends on interactive answers and on MCP servers you have not seen yet. If you want to know exactly what lands on disk before it lands, a template wins. If you want the assistant to keep producing Scenario tests and versioned prompts as the project grows, the AGENTS.md plus MCP combination is the reason to pick this.
Maintenance, release cadence and licence
The release history shows v0.1.21 in December 2025, v0.1.22 in January 2026 and v0.1.23 in February 2026, with the last push to main in June 2026. That is a roughly monthly patch cadence on a 0.1.x version line, which tells you the interface is still settling: expect the generated tree and the CLI prompts to change between minor releases. Because the CLI is global, upgrading means reinstalling the package, and projects generated by an older version will not pick up new AGENTS.md content automatically. There is no documented upgrade command in the material, so plan on regenerating or diffing by hand. The licence is MIT, which permits commercial use and modification; the README does not state a separate licence for generated output, and the LangWatch API key and Scenario dependency are governed by their own terms. That is a question for your legal team, not something to infer from the MIT label on the CLI.
Editorial conclusion
Adopt Better Agents if you are starting a new agent project in Agno, Mastra or LangGraph, you already use a supported coding assistant, and you are willing to keep prompts in YAML under prompts/ synced through prompts.json. Do not adopt it to retrofit an existing repository, to work in a framework the CLI does not offer, or if a LangWatch API key and the Scenario test dependency are unacceptable. Before committing, run better-agents init in a scratch directory and inspect three things: the AGENTS.md it writes, the .mcp.json server list for your framework, and whether tests/scenarios/example_scenario.test.py is something you can actually run in CI on Node.js 22 or newer.
Community notes