# simonw/files-to-prompt architecture

> Architecture diagram of the GitHub repository simonw/files-to-prompt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simonw/files-to-prompt
- Repository: https://github.com/simonw/files-to-prompt

## Overview

files-to-prompt is a small CLI utility that combines file contents into LLM-ready prompt text. Users provide file or directory paths on the command line or through stdin; the CLI discovers and filters files, reads their contents, formats each file, and writes the result to stdout or a chosen output file. The sampled CLI shows these runtime stages and output modes; the README documents the supported options.

Main entry points: [`files_to_prompt/cli.py`](https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py) (Command handler), [`files_to_prompt/__main__.py`](https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/__main__.py) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Invocation and input"]
  node_entry["CLI entry<br/>[__main__.py]"]
  node_cli["Command handler<br/>[cli.py]"]
  node_stdin["Stdin paths<br/>[cli.py]"]
end

subgraph group_processing["File processing"]
  node_discover["Path traversal<br/>[cli.py]"]
  node_filter["File filtering<br/>[cli.py]"]
  node_reader["Content reading<br/>[cli.py]"]
end

subgraph group_output["Formatting and output"]
  node_formats["Output formatting<br/>[cli.py]"]
  node_destination["Output destination<br/>[cli.py]"]
end

node_user(("User"))

node_user -->|"runs command"| node_entry
node_entry -->|"invokes"| node_cli
node_user -->|"provides paths"| node_cli
node_cli -->|"reads paths"| node_stdin
node_cli -->|"processes paths"| node_discover
node_discover -->|"filters entries"| node_filter
node_discover -->|"reads files"| node_reader
node_cli -->|"reads file"| node_reader
node_reader -->|"formats content"| node_formats
node_formats -->|"writes output"| node_destination
node_user -->|"selects file"| node_destination

click node_entry "https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/__main__.py"
click node_cli "https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py"
click node_stdin "https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py"
click node_discover "https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py"
click node_filter "https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py"
click node_reader "https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py"
click node_formats "https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py"
click node_destination "https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_cli,node_stdin,node_user toneBlue
class node_discover,node_filter,node_reader toneAmber
class node_formats,node_destination toneMint
```

## Components

### Invocation and input

- [CLI entry](https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/__main__.py): `files_to_prompt/__main__.py`
- [Command handler](https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py): `files_to_prompt/cli.py`
- [Stdin paths](https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py): `files_to_prompt/cli.py`

### File processing

- [Path traversal](https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py): `files_to_prompt/cli.py`
- [File filtering](https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py): `files_to_prompt/cli.py`
- [Content reading](https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py): `files_to_prompt/cli.py`

### Formatting and output

- [Output formatting](https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py): `files_to_prompt/cli.py`
- [Output destination](https://github.com/simonw/files-to-prompt/blob/main/files_to_prompt/cli.py): `files_to_prompt/cli.py`

### Other components

- **User**

## Connections

- User → CLI entry: runs command (evidence: `README.md`)
- CLI entry → Command handler: invokes (evidence: `files_to_prompt/__main__.py`)
- User → Command handler: provides paths (evidence: `README.md`)
- Command handler → Stdin paths: reads paths (evidence: `files_to_prompt/cli.py`)
- Command handler → Path traversal: processes paths (evidence: `files_to_prompt/cli.py`)
- Path traversal → File filtering: filters entries (evidence: `files_to_prompt/cli.py`)
- Path traversal → Content reading: reads files (evidence: `files_to_prompt/cli.py`)
- Command handler → Content reading: reads file (evidence: `files_to_prompt/cli.py`)
- Content reading → Output formatting: formats content (evidence: `files_to_prompt/cli.py`)
- Output formatting → Output destination: writes output (evidence: `files_to_prompt/cli.py`)
- User → Output destination: selects file (evidence: `README.md`)
