code2prompt: turning a codebase into a single Markdown prompt

The problem is context assembly, not code reading

Anyone who has asked a model to review a module knows the tedious part is not the question. It is collecting the files, deciding what to leave out, pasting them in an order the model can follow, and guessing whether the result will fit. code2prompt targets exactly that chore. The README describes it as generating a comprehensive Markdown file containing the content of your codebase, and the intended uses it lists are code analysis, documentation and improvement tasks. The audience is narrow but real: developers who already work with a chat model or a local LLM and want a repeatable way to produce the input. It is not an editor plugin, not an agent, and not a retrieval system. It is a formatter with opinions about what belongs in the prompt. That distinction matters, because the tool's quality is decided almost entirely by its filtering and layout, not by any cleverness in how it reads files.

What the tool actually produces

Two artefacts come out of a run. The first is a source tree: a hierarchical listing of the project structure, which the README calls intelligent source tree generation. The second is the file contents themselves, rendered as Markdown code blocks. Syntax highlighting is inferred from file extensions, and the README notes that line numbers can be added to source blocks for precise referencing. That combination is the whole product. A model receiving the tree first can reason about layout before it reads any code, which is a small but genuine improvement over a bare concatenation of files. The line-number option is aimed at a specific workflow: asking a model to point at a line, then finding it yourself. Whether the model uses those numbers correctly is not something the documentation addresses. Treat it as a convenience for the human reader more than a guarantee about model behaviour.

Filtering is where the real work happens

The reason a naive cat of every file fails is that repositories are full of things you do not want in a prompt: build output, vendored dependencies, lockfiles, binaries, test fixtures. code2prompt addresses this in two ways. It respects .gitignore rules, which the README frames as ensuring irrelevant files are excluded. It also accepts glob patterns for exclusion, shown in the quick start as --exclude "*/tests/*". These two mechanisms overlap but are not identical. A .gitignore encodes what the repository does not track; an exclude glob encodes what you do not want in this particular prompt. A file can be tracked and still be wrong to include, and a file can be ignored yet relevant. The tool gives you both levers, which is the right call. The documentation does not describe precedence when the two disagree, so if your project has an unusual ignore setup, verify the output rather than assuming.

Getting it running, and the flags worth knowing

Installation is a single command, either pip install code2prompt or, as the README recommends, pipx install code2prompt. The pipx route keeps the CLI isolated from your project environments, which is the sensible default for a tool you invoke across many repositories. Basic invocation takes one or more paths: code2prompt --path /path/to/your/code. Multiple --path arguments are supported, so a run can span a source directory and a separate library directory. Output goes to stdout by default, or to a file with --output project_summary.md. The README also documents a clipboard option for copying the generated prompt directly. For unusual file types there is --syntax-map, which pairs an extension with a language, formatted as extension:syntax. The example given is --syntax-map "inc:bash,customext:python,ext2:javascript", meaning .inc files are highlighted as bash. Multiple --syntax-map arguments are also accepted. This is the flag that decides whether an unfamiliar extension renders as a readable block or as plain text.

Templates, variables and the include mechanism

Output formatting is driven by Jinja2 templates, which is the most consequential design decision in the project. Instead of a fixed layout, you can define what the prompt looks like: a preamble, a section for the tree, a loop over files, a closing instruction. The README describes customizable prompt templates for tailoring output to specific AI tasks, plus two extensions to plain Jinja2. The first is an include mechanism for template imports, which lets a shared header or footer live in its own file and be reused across templates. The second is input variables, described as enabling dynamic prompt generation based on user input. Together these turn the tool from a one-shape exporter into something closer to a small build system for prompts. The cost is that templates are now an artefact you maintain. If your team standardises on one template, changes to it affect every prompt anyone generates, which is either the point or a hazard depending on who owns the file.

Token counting, and the limit it cannot fix

The README lists smart token management: counting and optimising tokens to stay compatible with model context limits. Counting is straightforward and useful. Optimising is a vaguer claim, and the documentation does not specify what form that takes, whether it is deduplication, truncation, or simply reporting a number so you can decide. The hard limit is structural. A tool that emits the entire codebase in one document cannot make a large repository fit a small context window. Once the output exceeds the model's limit, your options are to narrow the paths, add excludes, or switch to a retrieval approach that selects relevant files per query. code2prompt helps with the first two and does nothing for the third. For a mid-sized project, or for a focused subset of a large one, this is fine. For a monorepo, it is the wrong category of tool, and no amount of token accounting changes that.

Where a different approach fits better

The clearest alternative is retrieval over embeddings: index the repository into chunks, embed them, and at query time fetch only the passages relevant to the question. The difference in approach is fundamental. code2prompt is exhaustive and static, producing the same document regardless of what you intend to ask, and it relies on the model to find what matters within that document. Retrieval is selective and query-dependent, and it relies on the index to have surfaced the right chunks. Exhaustive wins when the question spans the whole project, such as a consistency review or a documentation pass, because nothing is missed. Selective wins when the repository is far larger than the context window, because it is the only option that fits. The two are complementary rather than competing, and a team using retrieval for daily questions may still want code2prompt for the occasional whole-project sweep. Choose based on whether your typical question is about the whole codebase or a corner of it.

Maintenance, packaging and licence

The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is the permissive end of the spectrum, and it imposes no copyleft obligation on your own code. It does mean you carry the usual permissive-licence caveat: the software is provided without warranty, so a bug in the output is your problem, not the author's. On maintenance, the repository is not archived and the last push recorded is 2026-07-07, but no releases were retrieved, so there is no version history in the supplied material to reason about. That makes upgrades hard to plan. If you install from PyPI, you are tracking whatever the current published version is; if you pin a version in a requirements file, you will not learn about changes until you deliberately bump it. Given that templates and syntax maps are configuration you write yourself, pinning is the lower-risk choice. Verify the current release situation on PyPI before committing to a versioning policy.

Editorial conclusion

Adopt code2prompt if you routinely hand whole directories to a model and want gitignore-aware filtering, glob excludes, Jinja2 templates and a token count in one command. Do not adopt it if your repository exceeds the context window of the model you use, or if you need per-file retrieval rather than a flat dump; a chunking or embedding-based retrieval tool is the better shape there. Before relying on it, run it once against a repository with a non-trivial .gitignore and a custom extension, confirm which files land in the output, and check the reported token count against your model's limit.

Official sources

1. Issues
2. License: MIT
3. raphaelmansuy/code2prompt on GitHub
4. README