AI in Leaf NewNewAI-native project context arrived in Leaf 5Leaf 5 gives assistants an explicit map of your app instead of making them infer routes, modules, configuration, and structure from scratch.Introduced in Leaf 5See how it works

Why AI struggles with most frameworks

AI does not usually fail because it cannot write code. It fails because the app gives it poor context.

Without a map, the assistant guesses, and you end up debugging the guesses.

How Leaf fixes this

Leaf 5 gives AI tools a reliable, shared map of your app. Projects created with Leaf CLI are AI-ready immediately, and Leaf MVC needs no extra AI configuration. An agent working inside the project reads .leaf/CONTEXT.md alongside the filesystem, then updates that shared context as the app changes.

Instant project understanding

Open an agent in the project and ask for the feature you want. It starts with Leaf's shared context, verifies that map against the live codebase, and keeps the context useful as it works.

That means fewer invented files, fewer mismatched APIs, and less cleanup after generation.

The shared context format NEW

.leaf/CONTEXT.md follows a small official format, leaf.context v1, so that edits from different assistants compose instead of colliding. What Claude writes today, Cursor can extend tomorrow, and Codex can clean up next week. Every project created through Leaf CLI ships with the template (lite, MVC, API and console apps alike), and leaf up carries it forward when scaling a lite app.

The format is plain markdown with a handful of rules:

• The first line is a marker, <!-- leaf.context v1 -->, so tools and agents can recognize the file. It is invisible when rendered and never edited.
• Sections are ## headings in a stable order: Working With This File, Project Summary, Current Goal, Architecture, External Providers, Coding Conventions, Recent Changes, Known Decisions, Future Ideas. Agents preserve sections they don't recognize and may add project-specific ones at the end.
• Placeholders are underscore-wrapped lines. When one contains agent:, it is an instruction to the next assistant: ask the user something, make a choice, then replace the line with the answer. This is how a fresh template bootstraps itself into real project memory.
• Entries are single lines wherever possible, so concurrent edits merge cleanly in git. Recent Changes entries are dated (* 2026-08-06 what changed), capped at five, newest first. Known Decisions always carry their reasoning, because a decision without its why gets relitigated by the next agent.
• The file never duplicates the codebase. Routes and models, along with modules and structure, live in code and in leaf context; the shared memory holds only what code cannot say: the goals and decisions, and the reasoning behind them. This is what keeps it from rotting.
• No secrets, ever. Environment keys are referenced by name only.

The file also opens with a short "Working With This File" section carrying these same rules, so an assistant that has never seen Leaf before still edits it correctly.

When to use leaf context

You do not need this command to make AI features work. Use it when the assistant cannot access your project folder, such as a web chat or another external tool.

leaf context

The command is deliberately the opposite half of .leaf/CONTEXT.md. The shared file holds what code cannot say (goals, decisions, reasoning) and never duplicates the codebase. leaf context scans the codebase and generates the mechanical map the file leaves out: app type, installed modules, actual route registrations with their handlers and middleware, models, schema files, and environment key names (names only, values never leave your machine). It then appends the shared memory, so one paste gives an external assistant both halves. It does not replace the two-way context used by agents working inside the project.

Teaching your assistant Leaf

Leaf ships two documents built for AI, and they do different jobs:

llms.txt is knowledge. A compressed reference of Leaf's APIs, conventions and config, written for models instead of people. Assistants fetch it when they need Leaf facts, the way you'd check the docs. If your AI tool supports doc URLs (most do), point it here and it can answer "how do I do X in Leaf" correctly.

The Leaf skill is behavior. It teaches an agent how to work in a Leaf project: which entry point to scaffold, how to read and write .leaf/CONTEXT.md without breaking the format, when to run leaf context, what the scaffolds give you, and where to send bug reports for the beta commands. It comes with reference files the agent loads per topic, so it stays accurate without stuffing everything into one prompt.

How to use them:

• Claude Code: save the skill as .claude/skills/leaf/SKILL.md in your project (or ~/.claude/skills/leaf/SKILL.md for every project), and Claude loads it automatically whenever Leaf work comes up.
• Cursor, Codex and any agent that reads AGENTS.md: new Leaf MVC apps already ship an AGENTS.md pointing at the skill and llms.txt, so there's no setup at all.
• Anything else: paste the skill's URL into your assistant's custom instructions, or just tell it to fetch https://leafphp.dev/ai/SKILL.md before working.

The short version: llms.txt makes your assistant know Leaf, the skill makes it behave like a Leaf developer, and .leaf/CONTEXT.md makes it know your project. The three stack.

Errors that carry their own fix

When something breaks, the error message is the first thing your assistant reads, and usually the only thing. So Leaf writes error messages the way a maintainer would answer a support ticket: what went wrong, what to do about it, and how the fix differs depending on how your app is set up.

That's a real crash screen. No googling, no source diving, no guessing which of five Stack Overflow answers applies to your setup. The remediation is the message, and it's honest about context: what works in Leaf MVC, what a lite app needs instead. Your assistant reads it once and fixes the problem, and so do you.

The crash screen itself is built for handoff too: Copy as Markdown turns the whole report (message, stack, request context, breadcrumbs) into something you can paste straight into a chat, and Open with AI sends it there directly.

Built to burn fewer tokens

Tokens are money and context is scarce, so Leaf's AI documentation is engineered like an API, not a book:

• One hop to any answer. Every reference file lives at a stable URL (leafphp.dev/ai/references/<topic>.md), covers one concern, and fits comfortably in context. No navigation, no pagination, no reading three pages to extract one fact.
• Footguns over prose. The skill's Known Footguns section is a list of the exact mistakes agents actually make, in one screen. Correcting a wrong assumption up front is hundreds of times cheaper than debugging it after.
• Errors skip the loop. The most expensive thing an assistant does is the try-fail-search-retry cycle. An error that names its own fix collapses that loop to one step, which is why we treat error strings as documentation and field-test them with real agents.
• Context lives in the project. .leaf/CONTEXT.md means your assistant doesn't re-derive your architecture every session. Reading one small file beats re-exploring a codebase, every time.

We measure this the direct way: AI agents build real apps on Leaf, we count every file they had to open and every retry they burned, and whatever cost them tokens becomes a fix. The error message in the screenshot above exists because an agent hit the unclear version of it and told us exactly what it needed to hear instead.

Predictable structure means better output

Leaf's structure is intentionally obvious. AI works better when the project has clear places for code to live.

my-app/
 app/
    controllers/
    database/
    models/
    routes/
    views/
 public/

This gives assistants a stable path for new controllers, models, routes, views, services, modules.

Real features, not toy examples

AI-assisted Leaf work is meant for actual product features.

From idea to feature

The Leaf AI workflow is simple:

1. Open an agent in your Leaf project.
2. Describe the feature you want.
3. Let the agent read the shared context and verify it against the current project.
4. Review and run the changes while the agent syncs useful project knowledge back.

For an external assistant without project access, run leaf context and paste the compact output into your conversation first.

With project memory in the loop, the assistant works more like a teammate than autocomplete.

Where this is going

AI in Leaf is not a bolt-on. Leaf 5 shapes the framework and CLI, along with the docs and project structure, around a future where humans and AI build software together.