May 18, 2025 · essay
Taming Large Codebases with a Tkinter GUI for code2prompt
Building a Python Tkinter GUI to simplify using the `code2prompt` CLI for better LLM context generation from large projects.
The short version
- LLM
- My LLM assistant (Google Gemini 2.5 Pro Preview 05-06) played a key role in iterating on the GUI design and Tkinter implementation details. 100% of all code was written with its help.
- Why
- To create a user-friendly desktop utility that simplifies the process of generating targeted prompts from large codebases using the `code2prompt` CLI, especially when dealing with numerous files and folders.
- Challenge
- Building an intuitive file/folder tree selection mechanism in Tkinter, managing selection states recursively, and correctly constructing complex `code2prompt` CLI commands with dynamic exclude patterns.
- Outcome
- A functional Python Tkinter application that allows users to browse a project, selectively include/exclude files and folders, configure `code2prompt` options, and execute the command, all from a simple GUI.
- AI approach
- The LLM acted as a Tkinter consultant and Python debugger, helping to structure the GUI layout, implement event handling, refine the file scanning logic, and troubleshoot subprocess communication.
- Learnings
- Tkinter's `ttk.Treeview` is versatile for displaying hierarchical data. Managing selection state externally (e.g., in a dictionary) is crucial for complex interactions like recursive toggling. `subprocess.Popen` is effective for running CLI tools and capturing their output in a GUI.
Why this project? The code2prompt CLI tool is incredibly useful for generating context-rich prompts from codebases. However, when dealing with large projects like my "Electron/Vue3/Ollama Multi-Modal AI Assistant" (with tens of thousands of files after including all dev dependencies and backend services), manually crafting --exclude patterns can become tedious and error-prone. I needed a more visual and interactive way to select exactly which files and folders should be included in the prompt. The source code for this helper GUI is available on GitHub: code2prompt-gui Repository.
The Challenge(s): The core challenge was to build a desktop GUI that could:
- Scan a project directory and display its structure in an intuitive tree format.
- Allow users to easily select or deselect entire folders (and their contents) or individual files.
- Provide input fields for common code2prompt command-line options.
- Dynamically construct the correct code2prompt command with appropriate --exclude arguments based on user selections.
- Execute the command and display its output within the GUI.
Initially, I considered PySimpleGUI, but its Tree element's lack of direct per-node checkbox control and the complexities around visually updating selections for large trees led me to opt for Python's built-in Tkinter library (using its themed widgets, ttk). This offered more fine-grained control over the treeview and item states, albeit with a bit more boilerplate. Key hurdles included implementing recursive selection toggling for folders in the tree and ensuring the generated exclude paths were minimal and correct.
The Outcome: The code2prompt_tkinter_helper.py script is a functional desktop application. It features:
- A project folder browser.
- An interactive file/folder tree where clicking an item toggles its selection state (and that of its children if it's a folder). Visual feedback is provided by prepending "[X]" or "[ ]" to item names.
- "Select All" / "Deselect All" buttons for quick global changes.
- A section for configuring code2prompt options like output file, template, token counting, line numbers, etc.
- A "Generate & Run code2prompt" button that constructs and executes the CLI command.
- A multiline text area to display the generated command and the live STDOUT/STDERR from code2prompt.
- Initial filtering to exclude common large directories like node_modules, .git, and venv from the scan, significantly speeding up processing for typical software projects.
The tool effectively translates GUI selections into a precise set of --exclude arguments, making it much easier to manage what goes into the code2prompt context window.
Key Learnings:
- Tkinter ttk.Treeview: It's quite capable for hierarchical data. Using item IDs (iid) mapped to custom data objects (like my FileSystemItem class) is essential for managing state. Manually updating item text (e.g., to show selection status) is feasible for visual feedback.
- Recursive Logic for Tree Operations: Functions to recursively toggle selections or traverse the tree structure are fundamental when dealing with folder hierarchies.
- State Management for UI: Maintaining a separate dictionary (tree_items_map) to track the true selection state of each file/folder, independent of the visual tree representation, proved robust.
- subprocess.Popen for CLI Tools: Allows running external commands and capturing their output. Using iter(process.stdout.readline, '') provides a way to stream output to the GUI for a more responsive feel, though careful handling of blocking calls is needed.
- Optimizing Exclude Lists: When a parent folder is deselected, its children don't need to be individually excluded. The logic in get_selected_and_excluded_paths aims to create this minimal set of exclude patterns.
The "AI" Approach: My LLM assistant was a patient partner in this, helping to brainstorm Tkinter layouts, write event handlers, debug issues with ttk.Treeview item manipulation, and refine the logic for constructing the subprocess command. It also helped draft the initial README for this helper tool!
This Tkinter helper, while simple, has already saved me considerable time and reduced the chance of errors when preparing large codebases for code2prompt. It's a good example of how a small, targeted GUI can significantly improve workflow for powerful CLI tools.