Guide
Find context
Your agent needs one fact from a large knowledge tree. This guide finds it in a few bounded steps and reads only the sections that answer the task.
Choose a starting route
| You have | Start with |
|---|---|
| A known area | cumaru tree <area> |
| A question, no exact term | cumaru context "<query>" |
| An exact identifier | rg -n -F -- "<term>" .cumaru |
| A known file | Read it directly. |
1. List candidates
Start shallow. Each row is a path and its one-line summary:
cumaru tree specs Pick the candidates whose summaries match the task. Recurse only into those directories.
2. Map the sections
Get the headings of a selected file with their line ranges:
cumaru map specs/auth.md Each row starts with a selector such as specs/auth.md:18,42.
3. Read only that section
cumaru get specs/auth.md:18,42 Stop when the evidence answers the task.
Rank by meaning
When you do not know where a fact lives, rank the files against a short English query. Each row is a path range and a score:
cumaru context "how sessions expire" - A Markdown row is a
getselector relative to.cumaru/. A source row starts with./and is relative to the project root.getcannot read it. Read it with a normal tool, such assed -n 'START,ENDp' PATH. - Scores are uncalibrated. Compare ordering and read the top results; no score proves absence.
- Without a model, a lightweight lexical scorer runs and can miss paraphrases. If the results are
weak, refine the query or switch to tree or exact search.
The lightweight scorer ranks whole files. Run
cumaru mapfirst and read only the relevant section. contextworks offline and never downloads. To use the optional encoder, a person must runcumaru model pull bge-micro-v2once (about 35 MB).
In an agent session
The cumaru-search skill applies these routes for your agent. With the read hook
installed, a cat of a .cumaru/ Markdown file is redirected to map and get.
Sources: tree, map, get, context, model, cumaru-search. Command details: CLI reference.