AI Hero: a course repository you clone, not a course you watch

What AI Hero is, and who the repository is actually for

AI Hero is a course, but the repository is not the course. The README describes it as the course Matt Pocock is building to take developers from zero to AI engineer, aimed at people moving from frontend, backend or full-stack work into AI. What is published here is the code: examples, exercises, libraries and SDKs, plus articles. The prose lives on aihero.dev, and the README says each example links to a corresponding article there.

That distinction decides who gets value from cloning it. If you learn by reading a finished implementation and running it, the examples directory is the product. If you want a syllabus with a defined start and end, the repository does not supply one; the README points you at the newsletter for updates instead of promising a sequence. The stated goal is a transition path for working web developers, and the TypeScript and pnpm setup assumes you are already comfortable in that toolchain. A developer coming from Python will spend the first hour translating idioms rather than learning AI engineering.

How the examples are organised and how one gets run

The repository is a pnpm workspace with a top-level examples directory, and the example folders are grouped by theme rather than by difficulty. The listing includes agents, model-context-protocol, vercel-ai-sdk, ai-engineer-roadmap, misc, plus shared and template directories prefixed with an underscore. The underscore prefix is a convention, not a rule the README spells out, but it reads as internal scaffolding: _shared holds code reused across examples, _templates holds starting points, and _TODO holds work not yet published.

The run mechanism is a single script. package.json defines "example" as tsx internal/run-example.ts, so the pnpm command passes its arguments into a TypeScript runner that resolves the example folder and executes it. The README's quickstart invokes it as pnpm run example v 01, which it describes as running the first example of examples/vercel-ai-sdk. The two arguments are a short slug and a two-digit index, which is why the README says "v 01" rather than a path. The runner lives in internal/, alongside other maintenance scripts such as reorder-examples.ts, add-gitkeeps.ts and run-input-log.ts, so the repository treats its own example catalogue as generated content that needs reordering and linting rather than as a hand-maintained folder tree.

Installing AI Hero and running your first example

The README gives four prerequisites steps and one run step. Node.js is required, with LTS recommended, and pnpm is installed through Corepack. From the repository root, dependency installation is a single command:

pnpm install

Before anything runs, the README asks for a .env file at the root of the project. It gives two alternatives, and you only need one of them:

# Your OpenAI API key
OPENAI_API_KEY=your-api-key

# OR your Anthropic API key
ANTHROPIC_API_KEY=your-api-key

The dependency list matches that choice: @ai-sdk/openai, @ai-sdk/anthropic and @ai-sdk/deepseek are all present, along with the ai package and @ai-sdk/react. The README notes that a guide for running the examples with local models is coming, so at the time of writing the documented path assumes a hosted provider key. With the .env in place, the first example runs as:

pnpm run example v 01

What you should see is the example in examples/vercel-ai-sdk executing through tsx. If it fails immediately, the two likely causes are a missing .env at the root rather than inside the example folder, and a pnpm version mismatch, since package.json pins packageManager to pnpm@8.15.6.

The evals tooling is part of the repository, not an add-on

Most course repositories ship examples and stop there. This one also ships the evaluation harness the examples are meant to be checked against. The package.json includes evalite at 0.8.0 and autoevals, and defines an all-examples script as evalite watch examples. A separate embed-datasets script runs internal/create-embeddings-from-dataset.ts with the env file loaded.

That combination points at a specific workflow the README does not spell out: examples are treated as things that can be evaluated, not just executed once to see output. Evalite is credited in the README as Matt Pocock's evals framework and is listed among the open-sourced libraries, so the repository doubles as a place where that tool is exercised on real material. If you are evaluating AI code for a team, this is the more interesting half of the repository. If you only want to see a streaming chat response, the eval scripts add dependencies and concepts you can ignore.

Where AI Hero is the wrong tool

The repository is explicit that parts of it are unfinished. The README says anything marked with TODO is, in its words, "well, you get it", and examples/_TODO exists as a directory. Following a course that is still being written means an example you want may be a stub, and the repository has no release history to indicate what changed between checkouts. There is nothing to pin against.

The second limitation is provider dependency. The documented setup requires an OpenAI or Anthropic API key in a .env file, and the local-model path is described as something that will be added later. If your constraint is that no prompt leaves your network, the documented quickstart does not satisfy it yet. Third, the licence is genuinely ambiguous from the outside: package.json declares "license": "GPL" while the repository metadata reports NOASSERTION, and LICENSE.md sits at the root. The README does not discuss what that means for reuse of the examples in your own product. If you intend to copy example code into a commercial codebase, read LICENSE.md yourself before you do.

How it differs from a video-first AI course

The obvious alternative is a video course or a written tutorial series, and the difference is not quality but artefact. A video course gives you a fixed sequence and a narrator who decides what you see next. AI Hero gives you a directory of self-contained runnable samples with a runner script, and the README's own description of the examples directory is that each example is a self-contained, runnable code sample demonstrating a concept or technique.

That means you can diff an example against your own code, run it, break it, and read the dependency versions that actually made it work. You cannot, however, ask it what to learn next. The repository's answer to that is the linked article on aihero.dev, which puts the sequencing back outside the code. The other difference is scope: this repository covers the Model Context Protocol through @modelcontextprotocol/sdk and @ai-sdk/react for UI work, which is a wider surface than a single-topic tutorial, but it is breadth across examples rather than depth in one.

Maintenance, upgrades and what the licence question costs you

The last push to the default branch was on 2026-08-06, roughly six weeks before this writing. The repository is not archived. There are no retrieved releases, so there is no versioned artefact to upgrade to; you track main.

That has a practical cost. The dependency list is broad and mostly caret-ranged, including ai at ^4.2.0, @ai-sdk/openai at ^1.1.0 and @ai-sdk/react at ^1.1.15, with evalite pinned exactly at 0.8.0 and @clack/prompts at 0.10.0. Caret ranges mean a fresh pnpm install can resolve different versions than the ones the examples were written against, and the AI SDK packages have moved quickly. If an example breaks after a fresh install, the lockfile is the thing to check first, and pnpm-lock.yaml is committed for that reason. renovate.json at the root indicates dependency updates are automated rather than batched by hand.

On licensing, package.json says GPL and the repository metadata says NOASSERTION. Those two statements do not agree, and the README does not resolve them. Treat the licence as something to read in LICENSE.md before reusing example code, and do not assume the permissive default that most example repositories carry.

Editorial conclusion

Adopt AI Hero if you already write TypeScript and want to read working AI code rather than watch someone describe it; the examples directory is the part the README says is being worked on, and each example links to a corresponding article. Skip it if you need a guided curriculum with a fixed order, or if you do not want to manage your own OpenAI or Anthropic key, since the quickstart requires one in a .env file at the repository root. Before committing, verify the licence file at the root, because package.json declares GPL while the repository metadata reports NOASSERTION, and check whether the example you want is still marked TODO.

Frequently asked questions

Official sources

1. ai-hero-dev/ai-hero on GitHub
2. Issues
3. Project website
4. README