Skip to content
Mayura

Get started

Using Mayura with AI coding agents

Point Claude Code, Cursor, Codex and other coding assistants at documentation that matches your installed Mayura version.

Coding assistants write better Mayura code when they read the documentation for the version you actually have installed, instead of guessing from memory. Mayura ships everything an assistant needs inside the package, and mayura init tells assistants where to find it.

What's in the package

After npm install mayura, these are in node_modules/mayura/:

File What it is
docs/ This documentation, as Markdown, for the installed version. Start at docs/README.md.
llms.txt An index of every page with a one-line description, in the llms.txt format.
llms-full.txt All of the documentation in one file, for assistants that prefer to load everything at once.
lib/<entry point>/dist/*.d.ts The exact types of every entry point, with doc comments.

Because these come from the package, they always match the code your project runs, even offline.

Projects created by mayura init

Every project mayura init creates has an AGENTS.md that tells assistants:

  • where the documentation is (node_modules/mayura/docs/ and llms-full.txt);
  • what the project is and which npm run scripts it has;
  • the rules assistants most often get wrong: import paths, explicit permissions, cost limits in micros, strict schemas for real models (.nullable(), not .optional()), checking result.status, keeping keys out of code, and testing offline.

It also has a CLAUDE.md that imports AGENTS.md, for assistants that read that file instead. Edit both freely; they are yours.

Adding Mayura guidance to an existing project

If your project already has an AGENTS.md (or CLAUDE.md, .cursorrules, copilot-instructions.md), add this:

## Mayura

This project uses Mayura (`mayura` on npm). Before writing Mayura code, read the documentation for the installed
version: node_modules/mayura/docs/README.md (index) or node_modules/mayura/llms-full.txt (everything in one file).

- Import from `mayura` or `mayura/<entry point>`, never `@mayura/...`.
- Grant permissions explicitly: `model:<adapter id>`, `tool:<tool id>`, `effect:<read|write|host>`, capabilities.
- Costs are in micros (1,000,000 = $1); set `limits.maxCostMicros` for runs that use paid models.
- Check `result.status` before `result.output`; `outcome_unknown` means reconcile, never retry blindly.
- Test offline with `scriptedModel` from `mayura/testing`.

The CLI works well for agents

  • npx mayura --help lists every command, and --help after any command explains it.
  • --json (or any piped output) prints one JSON document per command, with a status field, so an agent can read results reliably. Errors are JSON on stderr with a code and a message.
  • mayura init is plan-first: without --apply it writes nothing and prints every file it would create. It never replaces a file unless it is run again with --apply --confirm and the plan's digest, so an agent can't overwrite your work by accident.
  • The CLI never prompts for a token. Commands that talk to a server read it from standard input (--token-stdin), so it never appears in the command line or the agent's transcript.

Online

The same index is at the root of the repository: llms.txt.

Edit this page on GitHubView as Markdown