# Better Agents: a scaffolding CLI that teaches your coding assistant your agent framework

> Better Agents is an MIT-licensed TypeScript CLI that generates an agent project layout plus an AGENTS.md and .mcp.json, so Claude Code, Cursor, Kilocode or Antigravity already knows your framework and its testing conventions. The catch is that it is a starting point, not a runtime.

**langwatch/better-agents** — Standards for building agents, better

- Repository: https://github.com/langwatch/better-agents
- Stars: 1,561 · Forks: 149
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/langwatch-better-agents

## The problem Better Agents targets: an assistant that does not know your framework

Most agent projects fail at the seams, not in the model call. The prompt lives in a string literal, the regression test lives nowhere, and the evaluation notebook that proved the retrieval step worked was never committed. Better Agents is aimed at that gap. It is a CLI tool and a set of standards for agent building, and the README is explicit about the second half: the goal is to make your coding assistant an expert in whichever agent framework you pick, naming Agno, Mastra and LangGraph as examples.

The intended user is a developer starting a new agent project who already has a coding assistant open in a terminal or editor. The CLI interviews you about language, framework, assistant, LLM provider and API keys, then writes a project tree. What it does not do is run your agent. There is no runtime in the dependency list that would execute a LangGraph graph or an Agno team; the package ships a bin entry named better-agents and the dependencies are CLI plumbing such as @inquirer/prompts, chalk and commander. Treat it as a project generator with opinions, not a framework.

## What the generated structure actually contains

The README publishes the full tree, and it is worth reading as a specification rather than a screenshot. Agent code sits in app/ or src/ depending on the chosen framework. Alongside it you get tests/evaluations/ with a Jupyter notebook for offline evaluation, tests/scenarios/ with an end-to-end scenario test in either Python or TypeScript, and prompts/ holding YAML prompt files. A prompts.json acts as a prompt registry, .mcp.json configures MCP servers, AGENTS.md holds the development guidelines, and .env plus .gitignore round it out.

Two design choices stand out. First, prompts are versioned as files rather than embedded in code, with prompts.json as the registry; the README ties this to playground use and team collaboration. Second, the MCP configuration is treated as part of the scaffold, not an afterthought, so the assistant gets framework-specific context and Scenario test-writing context from the start. The scenario tests point at langwatch/scenario and are described as simulating a conversation with the agent to check it behaves as expected. That is a behavioural test, not a unit test, and the README frames the whole thing around an Agent Testing Pyramid documented separately.

## Installing Better Agents and initializing a first project

The README gives two installation routes. The global install puts a better-agents binary on your path; the npx route avoids installing anything permanently. Both come straight from the README.

```bash
npm install -g @langwatch/better-agents
```

Or, without a global install, run the initializer directly:

```bash
npx @langwatch/better-agents init my-agent-project
```

Once the binary is available, initialization takes a target directory. Passing a dot scaffolds into the current directory; passing a name creates a new one.

```bash
better-agents init .
better-agents init my-awesome-agent
```

After that command the CLI prompts you for programming language, agent framework, coding assistant, LLM provider and API keys. What you should see on success is the tree from the README: app/ or src/, tests/evaluations/ with example_eval.ipynb, tests/scenarios/ with example_scenario.test.py or .test.ts, prompts/ with sample_prompt.yaml, plus prompts.json, .mcp.json, AGENTS.md, .env and .gitignore. Open AGENTS.md first; it is the file that tells your assistant how the project expects features to be tested and prompts versioned.

Requirements are worth checking before you start. The README asks for Node.js 22+, npm or pnpm, one of Claude Code, Cursor, Antigravity (agy) or Kilocode CLI, a LangWatch API key from app.langwatch.ai/authorize, and your LLM provider key. Anonymous telemetry is on by default and is disabled with an environment variable:

```bash
BETTER_AGENTS_TELEMETRY=0
```

## The Node.js version mismatch you should resolve before filing a bug

There is a discrepancy a reader will hit. The README's Requirements section says Node.js 22+, while package.json declares "engines": { "node": ">=18.0.0" }. Those are different contracts: the engines field is what package managers enforce or warn on, and the README is what the maintainers say they support. If your toolchain is on Node 20 and you get an install warning or a runtime failure, the README is the stricter document and the one to trust. This is not a criticism of the project so much as a reminder that the engines field in a scaffold CLI is often left at a permissive default.

The second constraint is the assistant requirement. The README lists exactly four options, and three of them are named by their command: claude, agy, kilocode. If you use an assistant outside that list, the .mcp.json and AGENTS.md files will still be written, but nothing in the README promises your tool reads them. The MCP servers are described as making your coding assistant an expert in your framework and in writing Scenario tests, which assumes an assistant that consumes MCP configuration.

## Where Better Agents is the wrong tool

Better Agents is a greenfield tool. Every command in the README is init, and the README does not document a migration path for an existing repository, a way to add the structure to a project that already has its own layout, or a rollback if you dislike what init produced. If you have a working agent with its own test suite, running init over it means reconciling two structures by hand.

It is also not a runtime, an evaluation engine or a prompt-management server. The evaluation notebooks link to LangWatch's offline evaluation API, the prompt files link to LangWatch's prompt management CLI, and the scenario tests link to langwatch/scenario. Better Agents writes the files that point at those things. If you want a library that executes agents, this is the wrong layer. And if your team does not use LangWatch, several of the generated artifacts reference LangWatch documentation and require a LangWatch API key, which the README lists as a requirement rather than an option. That is a real coupling, and it is the main reason someone might scaffold by hand instead.

## How it differs from starting from a framework template

The obvious alternative is the starter template that Agno, Mastra or LangGraph already ship, or a general-purpose scaffolding tool like create-* generators. The difference is what gets generated. A framework template gives you working agent code in that framework's idiom and stops there. Better Agents keeps the framework as a choice you make during the prompt sequence, and spends its output on the surrounding discipline: scenario tests, evaluation notebooks, a prompt registry, MCP configuration and an AGENTS.md that encodes the conventions.

That trade-off cuts both ways. You get structure that a framework template will not give you, and you get a project whose testing story depends on langwatch/scenario and whose prompt story depends on LangWatch's prompt management CLI. A team that wants a single-vendor-free scaffold, or that already has its own testing conventions, gets less from this than from a plain template. The comparison is not which produces better agent code; neither writes much of it. It is which produces the conventions you were going to write anyway.

## Maintenance, releases and what the MIT licence leaves open

The repository is not archived, and the last push was on 2026-06-03, roughly three and a half months before this writing. Releases are tagged and follow a patch cadence: v0.1.21 on 2025-12-11, v0.1.22 on 2026-01-13, v0.1.23 on 2026-02-22, with package.json at 0.1.23. The project uses release-please for versioning and commitlint plus husky for commit hygiene, which suggests the release process is automated rather than manual. The version is still 0.x, so nothing about the generated layout is guaranteed stable across minor bumps.

Upgrade cost is low if you treat the scaffold as a one-time event: the CLI is a global or npx install, not a dependency of your agent, so a new version does not change your project unless you re-run init. The cost is higher if you adopt the generated AGENTS.md as a living document, because it encodes conventions that a later version might change. The licence is MIT, which is permissive and places no conditions on the generated project's own licensing; the README and package.json both state MIT. Nothing here is legal advice, and the generated files pull in LangWatch services whose own terms are separate from this repository's licence.

## Conclusion

Adopt Better Agents if you are starting a new agent project in Agno, Mastra or LangGraph and want the scenario tests, evaluation notebooks and prompt files laid out before the first feature lands, with a coding assistant that reads AGENTS.md and .mcp.json. Do not adopt it if you already have a working agent repository and no appetite for restructuring it, or if you want a runtime library rather than a scaffold. Before committing, verify three things against the repository: that your coding assistant is one of Claude Code, Cursor, Antigravity or Kilocode CLI, that you have a LangWatch API key from app.langwatch.ai/authorize plus your LLM provider key, and that your Node.js version satisfies the README's 22+ requirement rather than the package.json engines field, which reads >=18.0.0. The last push to the repository was on 2026-06-03.

## FAQ

### Is agent a legit company?

This question is about a company named Agent, not about the Better Agents project. Better Agents is an MIT-licensed CLI published by LangWatch as @langwatch/better-agents, and the README describes it as a CLI tool and a set of standards for agent building.

### What are the top 3 AI agents?

The README does not rank or compare AI agents. It names Agno, Mastra and LangGraph only as examples of agent frameworks that the coding assistant can be made an expert in during init.

### What are three types of agents?

The README does not classify agents into types. It describes one artifact, the agent project, and the structure Better Agents generates around it: agent code, scenario tests, evaluation notebooks and versioned prompts.

### Why are people using AI agents?

The README does not discuss motivation for using AI agents. It focuses on how to start an agent project so that features are tested, evaluated and have their prompts versioned, which it says makes the agent ready for production.

## Sources

- [Issues](https://github.com/langwatch/better-agents/issues)
- [langwatch/better-agents on GitHub](https://github.com/langwatch/better-agents)
- [License: MIT](https://github.com/langwatch/better-agents/blob/main/LICENSE)
- [README](https://github.com/langwatch/better-agents/blob/main/README.md)
- [Releases](https://github.com/langwatch/better-agents/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/langwatch-better-agents