Coding agents

Orbit is built so coding agents (Claude Code, Codex, Cursor, Copilot and others) can use it correctly on the first try: the whole format and API are in files the package ships, problems come with the fix, and maps can be checked without a browser.

Give your agent the docs

  • llms.txt is an index of the docs, and llms-full.txt is all of them in one file: the format, the API, recipes for each framework, theming and accessibility. Both ship in the package (node_modules/@restless-dreams/orbit/llms-full.txt, matching the installed version) and online for the latest release at https://cdn.jsdelivr.net/npm/@restless-dreams/orbit/llms.txt and https://cdn.jsdelivr.net/npm/@restless-dreams/orbit/llms-full.txt.
  • Tell the agent about them in your project’s AGENTS.md or CLAUDE.md:
## Mind maps

This project draws mind maps with Orbit (@restless-dreams/orbit). Before
writing a map or code that uses it, read
node_modules/@restless-dreams/orbit/llms-full.txt. Check every map with
`npx @restless-dreams/orbit validate --json <file>` and fix every diagnostic
it lists.

Install the skill

The package includes an agent skill in skills/orbit: a SKILL.md with instructions that Claude Code, Codex, Cursor and other agents load on their own when a task involves mind maps, with the format reference, recipes and theming guide next to it.

# With the skills CLI, for Claude Code, Codex, Cursor and more:
npx skills add restless-dreams/orbit
# The same, from the installed package:
npx skills add ./node_modules/@restless-dreams/orbit
# Claude Code, by hand:
cp -r node_modules/@restless-dreams/orbit/skills/orbit .claude/skills/

What agents can rely on

  • One way to do each thing. createOrbitMap(element, markdown, options) for any page, <orbit-map> without a build step, OrbitMindMap from @restless-dreams/orbit/react, @restless-dreams/orbit/marked for markdown pipelines and renderToSVGString without a browser. Every option has one name and is documented in the type declarations.
  • A starting point. npx @restless-dreams/orbit example > map.md writes a map that uses every feature; --yaml writes it as YAML.
  • Problems with the fix. Parsing is forgiving, and every problem is reported with its line and what to do about it: Unknown frontmatter key "rings" (ignored). Did you mean "showRings"?, Unknown theme "dark". Themes: paper, night, … Did you mean "night"?, view must be "focus" or "all" (the overview), got "overview".
  • Checks without a browser.
npx @restless-dreams/orbit validate --json map.md
{
  "valid": false,
  "flavor": "markdown",
  "root": "Product roadmap",
  "nodes": 22,
  "depth": 3,
  "diagnostics": [
    {
      "code": "unknown-attribute",
      "message": "Unknown attribute \"colour\", kept as a custom attribute. Did you mean \"color\"?",
      "line": 14,
      "severity": "warning"
    }
  ]
}

The command exits with 1 until the map is valid. In code, parseOrbit(source).diagnostics holds the same list, and { strict: true } throws on the first problem.

  • A picture of the result. npx @restless-dreams/orbit render map.md --out map.svg draws the map as a standalone SVG. Open it, or turn it into a PNG with any converter, to look at it.
  • Messages in the console for the usual setup mistakes: no element to draw in (Orbit needs an element to draw the map in, but got null…), a container without a height (The map has no height, so nothing shows…), and an unknown theme name.

Asking for a map

Agents do well with the map’s content and where it goes. For example:

  • “Turn the outline in NOTES.md into an orbit-md map in docs/roadmap.md and add it to the docs page with <orbit-map>. Check it with orbit validate.”
  • “Show our product areas as an Orbit map on the dashboard, in the cosmos theme, with each team’s status.”
  • “Generate a YAML map for Orbit from teams.json at build time and render it to SVG for the README.”