Skip to content
Back to search

cartotree

MarketplaceWorks with Claude CodeGitHub

AI-friendly codebase mapping CLI — annotated directory trees that save tokens

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kingluminance--cartotree/badge.svg)](/listings/kingluminance--cartotree)

HTML

<a href="/listings/kingluminance--cartotree"><img src="/api/listings/kingluminance--cartotree/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx cartotree

No install required.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 11 lines
  1. {
  2. "name": "cartotree",
  3. "owner": { "name": "kingluminance" },
  4. "plugins": [
  5. {
  6. "name": "cartotree",
  7. "source": "./",
  8. "description": "Find the right files with few tokens: locate / peek / links MCP tools + a navigation skill."
  9. }
  10. ]
  11. }
README.md · README · 246 lines
  1. # 🌲 cartotree
  2. > AI-friendly codebase mapping CLI — annotated directory trees that save tokens, not just space.
  3. [![npm version](https://img.shields.io/npm/v/cartotree)](https://www.npmjs.com/package/cartotree)
  4. [![license](https://img.shields.io/npm/l/cartotree)](./LICENSE)
  5. ---
  6. ## The Problem
  7. When you paste your project structure into an AI assistant, two things happen:
  8. 1. **Token waste** — Raw `tree` output burns hundreds of tokens on ASCII box characters with zero semantic value.
  9. 2. **Hallucination** — AI has no idea what each folder *does*, so it guesses wrong.
  10. ## The Solution
  11. cartotree generates a compact, annotated map of your codebase — folder descriptions, exported functions, and an AI-optimized serialization format that fits your architecture into a fraction of the tokens.
  12. ---
  13. ## Quick Start
  14. ```bash
  15. npx cartotree
  16. ```
  17. No install required.
  18. ---
  19. ## Output Formats
  20. ### Default — Annotated ASCII Tree
  21. ```
  22. my-app/
  23. ├── src/ # Core application source
  24. │ ├── components/ # Reusable UI components
  25. │ │ ├── Button.tsx <Button, ButtonProps>
  26. │ │ └── Modal.tsx <Modal, useModal>
  27. │ ├── hooks/
  28. │ │ └── useAuth.ts <useAuth, useUser>
  29. │ └── services/
  30. │ └── api.ts <fetchUser, postData>
  31. └── package.json
  32. ```
  33. ### `--ai` — Token-Optimized Serialization
  34. ```
  35. # cartotree fmt: name{desc}[children]<exports>
  36. my-app{Core application source}[src{Core application source}[components{Reusable UI components}[Button.tsx<Button,ButtonProps>,Modal.tsx<Modal,useModal>],hooks[useAuth.ts<useAuth,useUser>],services[api.ts<fetchUser,postData>]],package.json]
  37. ```
  38. ### `--json` — JSON Format
  39. ```json
  40. {
  41. "my-app": {
  42. "src": {
  43. "_desc": "Core application source",
  44. "components": {
  45. "Button.tsx": ["Button", "ButtonProps"],
  46. "Modal.tsx": ["Modal", "useModal"]
  47. }
  48. }
  49. }
  50. }
  51. ```
  52. ---
  53. ## Usage
  54. ```bash
  55. # Default annotated ASCII tree
  56. npx cartotree
  57. # AI-optimized single-line serialization
  58. npx cartotree --ai
  59. # JSON format
  60. npx cartotree --json
  61. # Copy to clipboard (paste directly into AI)
  62. npx cartotree --ai --copy
  63. # Sync into CLAUDE.md / AGENTS.md
  64. npx cartotree --ai --sync
  65. # Sync into custom file
  66. npx cartotree --sync .cursorrules
  67. # Limit depth
  68. npx cartotree --depth 2
  69. # No depth limit
  70. npx cartotree --full
  71. # Exclude patterns
  72. npx cartotree --exclude "tests,*.log"
  73. # Disable export parsing
  74. npx cartotree --no-exports
  75. ```
  76. ---
  77. ## Options
  78. | Option | Default | Description |
  79. |--------|---------|-------------|
  80. | `--ai` | false | AI-optimized compact serialization |
  81. | `--json` | false | JSON format |
  82. | `--copy` | false | Copy output to clipboard |
  83. | `--sync [file]` | CLAUDE.md | Inject into AI config file |
  84. | `--depth <n>` | 3 | Max traversal depth |
  85. | `--full` | false | No depth limit |
  86. | `--exclude <patterns>` | — | Comma-separated exclude patterns |
  87. | `--no-exports` | false | Disable export parsing |
  88. ---
  89. ## Configuration
  90. Create `.cartotreerc` in your project root to set persistent defaults:
  91. ```json
  92. {
  93. "default": {
  94. "ai": true,
  95. "exports": false,
  96. "depth": 3
  97. }
  98. }
  99. ```
  100. Now `npx cartotree` automatically runs with `--ai --no-exports`.
  101. ---
  102. ## Folder Annotations
  103. Add a `.folder.md` to any directory — the first line becomes the annotation:
  104. ```
  105. # Reusable UI components
  106. Atomic design system built with Radix UI primitives.
  107. ```
  108. cartotree also falls back to the first line of `README.md` if no `.folder.md` exists.
  109. ---
  110. ## Ignoring Files
  111. Create `.cartotreeignore` in your project root:
  112. ```
  113. # .cartotreeignore
  114. *.log
  115. temp
  116. coverage
  117. .env*
  118. ```
  119. `node_modules`, `.git`, `dist`, `build` are excluded by default.
  120. ---
  121. ## `--sync` Integration
  122. Running `cartotree --sync` injects the tree between marker tags:
  123. ```html
  124. <!-- CARTOTREE-START -->
  125. (auto-updated on every sync)
  126. <!-- CARTOTREE-END -->
  127. ```
  128. Works with `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, or any file.
  129. ---
  130. ## Export Parsing
  131. cartotree reads your source files and surfaces exported symbols directly in the tree:
  132. ```
  133. hooks/
  134. └── useAuth.ts <useAuth, useUser, AuthProvider>
  135. ```
  136. Supports `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs`.
  137. ---
  138. ## License
  139. MIT
  140. ---
  141. ## For AI agents: locate · peek · links
  142. cartotree also works as a navigation layer for coding agents (Claude Code, Cursor, Codex…):
  143. it keeps a local index so the agent finds the right files **without dumping grep output or whole files** into context.
  144. ```bash
  145. npx cartotree locate "abort JSONL stream on httpBatchStreamLink unsubscribe" # which files to open first
  146. npx cartotree peek packages/client/src/links/httpBatchStreamLink.ts abort unsubscribe # only the matching lines
  147. npx cartotree links httpBatchStreamLink # where a symbol is defined and called
  148. npx cartotree links src/foo.ts # imports, importers, files usually changed with it (git)
  149. ```
  150. ### Set it up so your agent uses it automatically
  151. ```bash
  152. npx cartotree init # skill + MCP server + SessionStart reminder (shows every change)
  153. npx cartotree init --dry-run # preview only
  154. ```
  155. Or as a Claude Code plugin:
  156. ```bash
  157. claude plugin marketplace add kingluminance/cartotree
  158. claude plugin install cartotree@cartotree
  159. ```
  160. The MCP server (`npx cartotree mcp`) exposes `cartotree_locate`, `cartotree_peek` and `cartotree_links`.
  161. After the first call the index stays in memory (~10 ms per lookup). An on-disk cache in `.cartotree/` is keyed by git HEAD and your uncommitted changes.
  162. ### How locate ranks files
  163. BM25F over four fields of every source file: path words, exported names, code identifiers (scored per function so one matching function is not diluted by a long file) and **past commit messages that touched the file**. Plus light stemming, an import-neighbor boost, 1–2 evidence lines per result, a warning when the top results are close, and "usually changes with" from git co-change history. No LLM, no network.
  164. ### Benchmark
  165. [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (21,632 files), 30 real commit messages → "which files were changed?", Claude Haiku agent, compared with the same agent using only ls/find/grep:
  166. | | grep only | cartotree (fast mode) |
  167. |---|---|---|
  168. | right file in top 3 | 13.5 / 15 | 14 / 15 |
  169. | tool-output tokens | ~37k | ~7.5k (**−80%**) |
  170. | total agent tokens | ~153k | ~100k (**−35%**) |
  171. | time | ~130 s | ~45 s (**−66%**) |
  172. Accuracy is on par with grep (±1 question across runs); the gain is cost and speed. Git history was cut off before the test commits to avoid leakage.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.