# FileBundler

```bash
uvx filebundler #  -> prints the version
uvx filebundler web [options] #  -> launches the web app
uvx filebundler web --headless #  -> no auto open
uvx filebundler web --theme #  -> light|dark
uvx filebundler web --log-level debug #  or one of [debug|info|warning|error|critical]
uvx filebundler cli tree [project_path] #  -> generates .filebundler/project-structure.md for the given project (default: current directory)
uvx filebundler mcp # -> starts the MCP server
```

## What is it?
FileBundler is a web app and CLI utility to bundle project files together and use them for LLM prompting. It helps estimate and optimize token and context usage.

# Who is FileBundler for?
If you're used to copying your files into your "chat of choice" and find the output is often better than the edits your AI powered IDE proposes then FileBundler is for you.

**Here are some reasons why:**
1. Segment your projects into topics (manually or with AI)
2. Optimize your LLM context usage
3. Copy fresh context in one click, no uploading files, no "Select a file..." dialog
4. It encourages you to use best practices, like [anthropic's use of xml tags](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags)

# How do I use it?
- install and run FileBundler per the command at the start of this README
- visit the URL shown on your terminal
- you'll be prompted to enter the path of your project (this is your local filesystem path)
  - you can copy the path to your folder and paste it there
  - <details><summary>why no file selection window</summary>we currently don't support a "Select file" dialog but we're open to it if this is a major pain point</details>
- This will load the <span style="color:green">file tree 🌳</span> on the sidebar and the tabs on the right
- The tabs will display your currently selected files, allow you to save them in a bundle and export their contents to be pasted on your chat of preference
- To save a bundle you need to enter a name. The name must be lowercase and include only hyphens ("-") letters and numbers

# Features
Besides creating bundles FileBundler has additional features

## Project Structure
The app automatically exports your project structure to a file called `project-structure.md` with computed token counts for each file and folder not ignored. Checkout the [.filebundler/project-structure.md](https://raw.githubusercontent.com/dsfaccini/filebundler/refs/heads/master/.filebundler/project-structure.md) file in this project

## Ignore patterns
Not all files are included in the `project-structure.md`. *Ignore patterns* are made from a combination of `DEFAULT_IGNORE_PATTERNS` defined in this project and the .gitignore file of the project you open.

Ignore patterns are stored in the `.filebundler/settings.json` file can be modified either directly in this file or using the *webapp* in the `Project Settings` tab on the sidebar you can add or remove glob patterns to ignore certain files or folders from the project structure.

## Estimate token usage
We currently use tiktoken with the [o200k_base](https://github.com/openai/tiktoken) model to compute token count, but you may a utility like [tokencounter.org](https://tokencounter.org/) to estimate token usage for other models or [openai's tokenizer](https://platform.openai.com/tokenizer) to compare estimates.

## Bundles
A bundle is just a list of file paths relative to their project folder. It includes some metadata, such as the total byte size of the files in the bundle and the total tokens as calculated by our tokenizer (currretly o200k_base). A bundle can be exported, that means, the contents of the files listed in a bundle can be exported as an XML structure. This follows the best practices [mentioned above](#who-is-filebundler-for). This exported code is also called a bundle. So for clarity, we'll speak of "XML bundle" or "code bundle" when we talk about the **bundle of exported code** and refer to the list of file paths as the "file bundle" or just "bundle".

### Persistance
Bundles are also persisted to the project whenever they are created using the web app. They are JSON files found under `.filebundler/bundles`. You can also create a bundle by writing such a JSON file in the bundles folder.

## Auto-Bundle
The auto-bundler uses an LLM to suggest you bundles relevant to your query. Simply choose your desired model from the "Select LLM model" dropdown; the app will automatically infer the correct provider (Anthropic or Gemini) and prompt you for the corresponding API key if needed. The auto-bundler automatically selects your exported project structure (which you can unselect if you want).

The auto-bundler will use your prompt and current selections to suggest bundles. The LLM will return a list of likely and probable files that are relevant to your query, and a message and/or code if you asked for it.

### Auto-Bundle example
A workflow example would be for you to provide the LLM with your TODO list (TODO.md) and ask it to provide you with the files that are related to the first n tasks. You could also ask it to sort your tasks into different categories and then re-prompt it to provide bundles for each category.

## Tasks
FileBundler will copy the templates under [tasks/templates/](https://github.com/dsfaccini/filebundler/tree/master/filebundler/features/tasks/templates) into the project's `.filebundler/tasks/` directory when filebundler is initialized. This is a useful task management workflow. This will have no effect as long as your AI coding agent doesn't read the file. To use the task management workflow, you need to tell your agent to follow the instructions of the task management workflow using a trigger word or phrase, like `use the task management system whenever I tell you to "tackle a task"`.

## MCP
FileBundler includes a Model Context Protocol (MCP) server that allows AI-powered IDEs and other tools to programmatically request file bundles. This enables an LLM to receive the content of multiple specified files in a single, efficient transaction, potentially reducing interaction time and costs associated with multiple individual file-reading tool calls.

The server provides a tool named `export_file_bundle` which accepts a list of relative file paths, the absolute project path, and an optional bundle name. It returns an XML-formatted string containing the content of these files, ready for LLM consumption.

### Running the MCP server
`python -m filebundler mcp`
`uvx filebundler mcp`

### Add the MCP server via JSON (like on Cursor)
{
    "mcpServers": {
      "filebundler-server": {
        "command": "uvx filebundler mcp",
        "args": [
          "filebundler\\mcp_server.py"
        ],
        "description": "A simple MCP server to query top chatters from a community database"
      }
    }
  }

### Integrating with AI IDEs (e.g., Cursor)
Many AI-assisted IDEs, such as Cursor, allow you to define custom tools that can be invoked by the AI. To integrate FileBundler's MCP server:

1.  **Ensure FileBundler is installed** in your project's Python environment or globally accessible.
2.  **Configure the custom tool** in your IDE. The specifics might vary, but generally, you'll need to provide:
    *   **Command**: `python -m filebundler mcp`
        *   *Note: Using `python -m filebundler mcp` is generally more robust as it ensures the correct Python environment is used, especially if you have multiple Python versions or virtual environments. If `uvx filebundler mcp` is preferred and `uvx` is reliably in your IDE's execution PATH, that can also be used.*
    *   **Communication Protocol**: Stdio (Standard Input/Output)
    *   **Working Directory**: (If applicable) Set this to your project's root directory. The `project_path` argument to the `export_file_bundle` tool also needs to be the absolute path to your project.

Once configured, the AI in your IDE should be able to call the `export_file_bundle` tool, providing it with a list of file paths (relative to the project root) and the absolute `project_path` to get a bundled context.

For details on how to run the MCP server via the command line, see the [CLI Usage](#cli-usage) section.

## Supported LLM models
The auto-bundler supports models from multiple providers (Anthropic and Gemini). Simply choose any supported model from the "Select LLM model" dropdown; the app will infer its provider and prompt for the matching API key (e.g. `ANTHROPIC_API_KEY` or `GEMINI_API_KEY`). To add more models or providers, extend the `MODEL_REGISTRY` in `filebundler/lib/llm/registry.py`.

# Roadmap
[TODO.md](https://raw.githubusercontent.com/dsfaccini/filebundler/refs/heads/master/TODO.md)
We plan on adding other features, like codebase indexing

# Performance and debugging
If your application **doesn't start or freezes** you can check the logs in your terminal.

If your application **hangs** on certain actions, you can debug using logfire. For this you'll need to stop FileBundler, set your logfire token and re-run the app.

You can set your logfire token like this
<details>
<summary>Unix/macOS</summary>

```bash
export LOGFIRE_TOKEN=your_token_here
```
</details>

<details>
<summary>Windows</summary>

```powershell
# using cmd
set LOGFIRE_TOKEN=your_token_here

# or in PowerShell
$env:LOGFIRE_TOKEN = "your_token_here"
```
</details>

For any other issues you may open an issue in the [filebundler repo](https://github.com/dsfaccini/filebundler).

# Similar tools

## [Cursor](https://www.cursor.com/)
Currently, you can add project rules to your project and include globs for files related to those rules. This is kind of a reverse file bundler, since cursor uses the files in the glob to determine what rules you send to the LLM.
You can as well make a selection of files to be included in a chat, but you don't have an overview of how much context has been used. To clear the context you can start a new chat, but the selection you made for the previous chat won't be persisted (as of today), so you need to reselect your files.

## RepoPrompt
Before I started this tool I researched if there was already an existing tool and stumbled upon [Repo Prompt](https://x.com/RepoPrompt), which I believe is built by @pvncher. Some reasons I decided against using it were:
1. currently waitlisted
2. currently not available for Windows
3. closed source
4. pricing

For the record it seems like a great tool and I invite you to check it out. It offers lots of other functionality, like diffs and code trees.

## [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)
Like cursor but on the CLI. With the introduction of [commands](https://x.com/_catwu/status/1900593730538864643) you can save markdown files with your prompts and issue them as commands to claude code. This is a bit different than bundling project files into topics, but shares the concept of persisting workflows that you repeat as settings.

## aider
TODO

# Useful references
- [anthropic's prompt library](https://docs.anthropic.com/en/prompt-library)
- [anthropic's long context tips](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/long-context-tips#example-multi-document-structure)

# LICENSE
We use GPLv3. Read it [here](https://raw.githubusercontent.com/dsfaccini/filebundler/refs/heads/master/LICENSE)

## CLI Usage

FileBundler now supports a CLI mode for project actions without starting the web server.

- To generate the project structure markdown file for your project, run:

```bash
uvx filebundler cli tree [project_path]
```
- `project_path` is optional; if omitted, the current directory is used.
- The output will be saved to `.filebundler/project-structure.md` in your project.

- To start the Model Context Protocol (MCP) server, run:

```bash
uvx filebundler mcp
```
- This server allows LLMs or other MCP-compatible clients to request file bundles programmatically. It listens on stdio.

- To launch the web app (default):

```bash
uvx filebundler web [options]
```

- If you run `uvx filebundler` with no subcommand, it prints the current version