TreeMapper

⚠️ DEPRECATED. TreeMapper is sunset. It has always been a thin wrapper around the diffctx engine, and diffctx now covers 100% of its functionality — same CLI surface, same flags, same Python API, same MCP server. This is the final release; no further updates will be published under the treemapper name.

Migrate:
pipx uninstall treemapper && pipx install diffctx
Then replace treemapper → diffctx, treemapper-mcp → diffctx-mcp, and import treemapper → import diffctx. Every command and API call works unchanged.

Map a codebase into LLM-ready context. TreeMapper serializes an entire directory tree — structure plus file contents — to YAML, JSON, Markdown, or text, and selects the minimal smart git-diff context needed to understand a change. Paste the output into Claude, ChatGPT, or any LLM.

TreeMapper is a thin command-line product built on the diffctx engine. All traversal, serialization, and diff-context selection live in diffctx; TreeMapper re-exposes them under the treemapper name so there is a single source of truth and no duplicated logic.

Installation

pipx install treemapper                  # recommended: isolated, no venv needed
pip install treemapper                   # or with pip
pip install 'treemapper[tree-sitter]'    # + AST parsing for smarter diff context
pip install 'treemapper[mcp]'            # + MCP server for AI assistants

Usage

treemapper .                     # map current directory to Markdown (stdout)
treemapper /path/to/project      # map a specific directory
treemapper . -f json             # output as JSON
treemapper . -f md --save        # save as tree.md
treemapper . --no-content        # structure only, no file contents
treemapper . -c                  # copy output to clipboard
treemapper . --diff HEAD~1       # smart context for the last commit
treemapper . --diff main..HEAD   # smart context for a branch range
treemapper graph .               # project dependency graph (mermaid)

Two modes

Tree mapping (treemapper .) — walks the directory tree, respects hierarchical ignore patterns (.gitignore, .diffctx/ignore), reads file contents with binary/encoding detection, and serializes the result.
Diff context (treemapper . --diff) — analyzes a git diff and selects the minimal set of code fragments needed to understand the change, instead of dumping whole files.

Run treemapper --help for the full flag reference.

Python API

import treemapper

tree = treemapper.map_directory(".", no_content=False)
print(treemapper.to_yaml(tree))

context = treemapper.build_diff_context(root_dir=".", diff_range="HEAD~1")

# treemapper.run drives the full branded CLI from Python (same surface as the command)
treemapper.run(["graph", "."], prog="treemapper", version=treemapper.__version__)

Every run reports an exact tiktoken token count (not a chars / 4 estimate), so you know the real context cost before you paste.

Relationship to diffctx

TreeMapper is the user-facing distribution; diffctx is the reusable engine. Pin compatibility is diffctx>=1.10.1,<2.0. If you are embedding the engine in your own tool, depend on diffctx directly.

License

Apache 2.0

Metadata

Release files for treemapper 2.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for treemapper 2.4.0
File	Size	Uploaded
treemapper-2.4.0.tar.gz	10.7 kB	Jul 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for treemapper 2.4.0
File	Interpreter	ABI	Platform	Reset
treemapper-2.4.0-py3-none-any.whl 8.8 kB Jul 17, 2026	Python 3	none	any	Details

Total release size: 19.6 kB

Release files / treemapper-2.4.0.tar.gz

Download URL	treemapper-2.4.0.tar.gz
Size	10.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`ec0f513feba09fa4fcf9f13f54545a0bafd1a7f0ae7d79ffd293c10c3383f6f3`
BLAKE2b-256 checksum How to use checksums	`9d00c3ae1b8aaaf40fa0d93f60496b53fe0d71ce0e8e9a8458fce9a29cc34bfa`
Upload date	Jul 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/nikolay-e/treemapper
Publishing commit: github.com/nikolay-e/treemapper/tree/1923cfb95385d013d6a9cd0f2720a7ab385b7740

Workflow

Publishing configuration: github.com/nikolay-e/treemapper/blob/1923cfb95385d013d6a9cd0f2720a7ab385b7740/.github/workflows/cd.yml
Publishing logs: github.com/nikolay-e/treemapper/actions/runs/29616218226/attempts/1

Artifact

Subject: treemapper-2.4.0.tar.gz
SHA-256 checksum: ec0f513feba09fa4fcf9f13f54545a0bafd1a7f0ae7d79ffd293c10c3383f6f3 Verifying attestations

Release files / treemapper-2.4.0-py3-none-any.whl

Download URL	treemapper-2.4.0-py3-none-any.whl
Size	8.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`62c43e964d49da2adfd243c2efbad36616a2223be7cc016cf5a847f3adfc3767`
BLAKE2b-256 checksum How to use checksums	`e6458f16338fc0ad18a3ec1cda974c418102fcd1c6be2e80a5935666dcb68995`
Upload date	Jul 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/nikolay-e/treemapper
Publishing commit: github.com/nikolay-e/treemapper/tree/1923cfb95385d013d6a9cd0f2720a7ab385b7740

Workflow

Publishing configuration: github.com/nikolay-e/treemapper/blob/1923cfb95385d013d6a9cd0f2720a7ab385b7740/.github/workflows/cd.yml
Publishing logs: github.com/nikolay-e/treemapper/actions/runs/29616218226/attempts/1

Artifact

Subject: treemapper-2.4.0-py3-none-any.whl
SHA-256 checksum: 62c43e964d49da2adfd243c2efbad36616a2223be7cc016cf5a847f3adfc3767 Verifying attestations