Field notes on context for AI agents

Give your AI agents roots.

Cumaru turns your repository into a knowledge tree. Agents read the index first, then load only the branches the task needs.

fig. 1 Dipteryx odorata, the cumaru tree, with its fruit.

Cumaru seeds arranged on wood in the shape of a tree.one seed = one filea branch = a spec areathe trunk = the index
fig. 2 Seeds arranged as a tree. One seed is one file, a branch is a spec area, and the trunk is the index.

p.01 Method

Every file is a seed. The index is the tree.

  1. 01 Index

    Every .cumaru/ node has an index and a one-line summary, so an agent sees what exists before it reads anything.

    How the tree works
  2. 02 Prune

    The agent lists the candidates and keeps only the ones relevant to the task.

    Find context
  3. 03 Load

    It reads the selected sections and nothing else. Finished work goes back into the tree.

    Ownership

p.02 Index

The CLI shows the branches before anyone reads them.

Example task: tune the motion rules of this site. The agent lists the spec areas, keeps one, outlines it, and loads ten lines.

Real output, captured in this repository on 2026-11-22. The map step shows only its ### rows.

cumaru tree specs

  • [ ] specs/documentation/ Public documentation entry points and installation guidance on cumaru.dev.
  • [x] specs/styles/ Visual language of cumaru.dev: color tokens, typography, button pattern, header, and motion rules.

cumaru map specs/styles

  • [ ] :19,24 ### Tokens
  • [ ] :26,29 ### Typography
  • [ ] :31,38 ### Buttons
  • [ ] :40,51 ### Hero layout
  • [ ] :53,58 ### Header
  • [ ] :60,62 ### Page shell and footer
  • [ ] :64,67 ### Commands and tabs
  • [ ] :69,75 ### Documentation layout
  • [x] :77,86 ### Motion
  • [ ] :88,105 ### Motion study surface

cumaru get specs/styles/index.md:77,86

  • [x] 10 lines loaded of the 141 in specs/styles/index.md

p.03 Cycle

Ideas grow into plans. Plans settle into specs.

When work closes, its delta is absorbed into the spec that owns it. The knowledge stays in your repository, across agents, models, and framework updates. Who owns what

  1. exploring/

    Ideas incubate

    Pre-plan ideas with no commitment. Never loaded by default.

  2. plans/

    Work happens

    One directory per item: tasks, handoffs, evidence, and the delta draft.

  3. specs/

    Knowledge settles

    What is true now. On close, the delta is absorbed and the plan is removed.

p.04 Start

New idea or existing code?

Both paths start with a domain. Compare domains.

p.05 Install

Plant it.

Install the CLI, then let your agent climb.

Script

curl -fsSL https://raw.githubusercontent.com/rntgspr/cumaru/main/src/install.sh | bash

Homebrew

brew install rntgspr/tap/cumaru

npm

npm install --global @cumaru/cumaru

Set up your project Full install guide

Portrait of an Indigenous man drawn in typewriter characters.

p.06 Adopters

Who uses Cumaru?