{"id":13562828,"url":"https://github.com/simonw/files-to-prompt","last_synced_at":"2025-05-14T18:01:58.642Z","repository":{"id":229186568,"uuid":"776058601","full_name":"simonw/files-to-prompt","owner":"simonw","description":"Concatenate a directory full of files into a single prompt for use with LLMs","archived":false,"fork":false,"pushed_at":"2025-02-19T05:57:43.000Z","size":49,"stargazers_count":1507,"open_issues_count":14,"forks_count":107,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-04-13T11:44:18.838Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simonw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"simonw"}},"created_at":"2024-03-22T15:42:41.000Z","updated_at":"2025-04-13T10:25:30.000Z","dependencies_parsed_at":"2024-03-22T17:10:17.494Z","dependency_job_id":"63244ac7-82cc-4de3-b7da-198c675d06ba","html_url":"https://github.com/simonw/files-to-prompt","commit_stats":{"total_commits":17,"total_committers":3,"mean_commits":5.666666666666667,"dds":"0.11764705882352944","last_synced_commit":"3332a864d3532afd429adf1aece9b27a812c9d8c"},"previous_names":["simonw/files-to-prompt"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Ffiles-to-prompt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Ffiles-to-prompt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Ffiles-to-prompt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Ffiles-to-prompt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonw","download_url":"https://codeload.github.com/simonw/files-to-prompt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198452,"owners_count":22030964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T13:01:12.601Z","updated_at":"2025-05-14T18:01:57.785Z","avatar_url":"https://github.com/simonw.png","language":"Python","funding_links":["https://github.com/sponsors/simonw"],"categories":["Python","Agent workflow highlights"],"sub_categories":[],"readme":"# files-to-prompt\n\n[![PyPI](https://img.shields.io/pypi/v/files-to-prompt.svg)](https://pypi.org/project/files-to-prompt/)\n[![Changelog](https://img.shields.io/github/v/release/simonw/files-to-prompt?include_prereleases\u0026label=changelog)](https://github.com/simonw/files-to-prompt/releases)\n[![Tests](https://github.com/simonw/files-to-prompt/actions/workflows/test.yml/badge.svg)](https://github.com/simonw/files-to-prompt/actions/workflows/test.yml)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/simonw/files-to-prompt/blob/master/LICENSE)\n\nConcatenate a directory full of files into a single prompt for use with LLMs\n\nFor background on this project see [Building files-to-prompt entirely using Claude 3 Opus](https://simonwillison.net/2024/Apr/8/files-to-prompt/).\n\n## Installation\n\nInstall this tool using `pip`:\n\n```bash\npip install files-to-prompt\n```\n\n## Usage\n\nTo use `files-to-prompt`, provide the path to one or more files or directories you want to process:\n\n```bash\nfiles-to-prompt path/to/file_or_directory [path/to/another/file_or_directory ...]\n```\n\nThis will output the contents of every file, with each file preceded by its relative path and separated by `---`.\n\n### Options\n\n- `-e/--extension \u003cextension\u003e`: Only include files with the specified extension. Can be used multiple times.\n\n  ```bash\n  files-to-prompt path/to/directory -e txt -e md\n  ```\n\n- `--include-hidden`: Include files and folders starting with `.` (hidden files and directories).\n\n  ```bash\n  files-to-prompt path/to/directory --include-hidden\n  ```\n\n- `--ignore \u003cpattern\u003e`: Specify one or more patterns to ignore. Can be used multiple times. Patterns may match file names and directory names, unless you also specify `--ignore-files-only`. Pattern syntax uses [fnmatch](https://docs.python.org/3/library/fnmatch.html), which supports `*`, `?`, `[anychar]`, `[!notchars]` and `[?]` for special character literals.\n  ```bash\n  files-to-prompt path/to/directory --ignore \"*.log\" --ignore \"temp*\"\n  ```\n\n- `--ignore-files-only`: Include directory paths which would otherwise be ignored by an `--ignore` pattern.\n\n  ```bash\n  files-to-prompt path/to/directory --ignore-files-only --ignore \"*dir*\"\n  ```\n\n- `--ignore-gitignore`: Ignore `.gitignore` files and include all files.\n\n  ```bash\n  files-to-prompt path/to/directory --ignore-gitignore\n  ```\n\n- `-c/--cxml`: Output in Claude XML format.\n\n  ```bash\n  files-to-prompt path/to/directory --cxml\n  ```\n\n- `-m/--markdown`: Output as Markdown with fenced code blocks.\n\n  ```bash\n  files-to-prompt path/to/directory --markdown\n  ```\n\n- `-o/--output \u003cfile\u003e`: Write the output to a file instead of printing it to the console.\n\n  ```bash\n  files-to-prompt path/to/directory -o output.txt\n  ```\n\n- `-n/--line-numbers`: Include line numbers in the output.\n\n  ```bash\n  files-to-prompt path/to/directory -n\n  ```\n  Example output:\n  ```\n  files_to_prompt/cli.py\n  ---\n    1  import os\n    2  from fnmatch import fnmatch\n    3\n    4  import click\n    ...\n  ```\n\n- `-0/--null`: Use NUL character as separator when reading paths from stdin. Useful when filenames may contain spaces.\n\n  ```bash\n  find . -name \"*.py\" -print0 | files-to-prompt --null\n  ```\n\n### Example\n\nSuppose you have a directory structure like this:\n\n```\nmy_directory/\n├── file1.txt\n├── file2.txt\n├── .hidden_file.txt\n├── temp.log\n└── subdirectory/\n    └── file3.txt\n```\n\nRunning `files-to-prompt my_directory` will output:\n\n```\nmy_directory/file1.txt\n---\nContents of file1.txt\n---\nmy_directory/file2.txt\n---\nContents of file2.txt\n---\nmy_directory/subdirectory/file3.txt\n---\nContents of file3.txt\n---\n```\n\nIf you run `files-to-prompt my_directory --include-hidden`, the output will also include `.hidden_file.txt`:\n\n```\nmy_directory/.hidden_file.txt\n---\nContents of .hidden_file.txt\n---\n...\n```\n\nIf you run `files-to-prompt my_directory --ignore \"*.log\"`, the output will exclude `temp.log`:\n\n```\nmy_directory/file1.txt\n---\nContents of file1.txt\n---\nmy_directory/file2.txt\n---\nContents of file2.txt\n---\nmy_directory/subdirectory/file3.txt\n---\nContents of file3.txt\n---\n```\n\nIf you run `files-to-prompt my_directory --ignore \"sub*\"`, the output will exclude all files in `subdirectory/` (unless you also specify `--ignore-files-only`):\n\n```\nmy_directory/file1.txt\n---\nContents of file1.txt\n---\nmy_directory/file2.txt\n---\nContents of file2.txt\n---\n```\n\n### Reading from stdin\n\nThe tool can also read paths from standard input. This can be used to pipe in the output of another command:\n\n```bash\n# Find files modified in the last day\nfind . -mtime -1 | files-to-prompt\n```\n\nWhen using the `--null` (or `-0`) option, paths are expected to be NUL-separated (useful when dealing with filenames containing spaces):\n\n```bash\nfind . -name \"*.txt\" -print0 | files-to-prompt --null\n```\n\nYou can mix and match paths from command line arguments and stdin:\n\n```bash\n# Include files modified in the last day, and also include README.md\nfind . -mtime -1 | files-to-prompt README.md\n```\n\n### Claude XML Output\n\nAnthropic has provided [specific guidelines](https://docs.anthropic.com/claude/docs/long-context-window-tips) for optimally structuring prompts to take advantage of Claude's extended context window.\n\nTo structure the output in this way, use the optional `--cxml` flag, which will produce output like this:\n\n```xml\n\u003cdocuments\u003e\n\u003cdocument index=\"1\"\u003e\n\u003csource\u003emy_directory/file1.txt\u003c/source\u003e\n\u003cdocument_content\u003e\nContents of file1.txt\n\u003c/document_content\u003e\n\u003c/document\u003e\n\u003cdocument index=\"2\"\u003e\n\u003csource\u003emy_directory/file2.txt\u003c/source\u003e\n\u003cdocument_content\u003e\nContents of file2.txt\n\u003c/document_content\u003e\n\u003c/document\u003e\n\u003c/documents\u003e\n```\n\n## --markdown fenced code block output\n\nThe `--markdown` option will output the files as fenced code blocks, which can be useful for pasting into Markdown documents.\n\n```bash\nfiles-to-prompt path/to/directory --markdown\n```\nThe language tag will be guessed based on the filename.\n\nIf the code itself contains triple backticks the wrapper around it will use one additional backtick.\n\nExample output:\n`````\nmyfile.py\n```python\ndef my_function():\n    return \"Hello, world!\"\n```\nother.js\n```javascript\nfunction myFunction() {\n    return \"Hello, world!\";\n}\n```\nfile_with_triple_backticks.md\n````markdown\nThis file has its own\n```\nfenced code blocks\n```\nInside it.\n````\n`````\n\n## Development\n\nTo contribute to this tool, first checkout the code. Then create a new virtual environment:\n\n```bash\ncd files-to-prompt\npython -m venv venv\nsource venv/bin/activate\n```\n\nNow install the dependencies and test dependencies:\n\n```bash\npip install -e '.[test]'\n```\n\nTo run the tests:\n\n```bash\npytest\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonw%2Ffiles-to-prompt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonw%2Ffiles-to-prompt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonw%2Ffiles-to-prompt/lists"}