How MashuPack works

Overview

MashuPack packages a local codebase into a single structured text file that AI tools can navigate like a real project.

The common objection: "stuffing a whole repo into an AI ruins its attention." That's true for naive copy-paste dumps. But modern AI tools like Claude and ChatGPT have internal environments — they can execute code, grep, search, and navigate structured text the same way a developer would in a terminal. When the export has clear file path headers and explicit boundaries, the AI doesn't have to read everything at once. It finds what it needs, reads that file, traces imports, and moves on.

MashuPack's job is to make that export as clean and navigable as possible: select the right files, package them with structured headers, and give the AI something it can actually work with — not a wall of text.

Everything runs in your browser. Nothing is uploaded to any server.

Privacy

MashuPack reads your files through your browser's built-in File System Access API. When you drop a folder or use the folder picker, your browser gives MashuPack read access to that folder. MashuPack builds the file tree, calculates stats, and holds everything in memory. No data is uploaded to any server. There is no MashuPack server for it to go to.

File contents are read only when you actually need them — when you preview a file in the viewer, or when you export. Everything else (the tree, stats, file names, sizes) comes from filesystem metadata, which is much lighter.

Loading a project

Two ways to load a folder:

• Drag and drop — drag a folder from your file manager and drop it anywhere on the app. A full-screen drop target appears as you drag.
• Folder picker — click "Browse for folder" to open a native folder picker dialog.

MashuPack scans the folder and builds the file tree. For most projects this is nearly instant. For very large repositories, see Large repos.

To start fresh, click "Clear project" in the top bar. Your current project is discarded and the drop zone reappears.

Browsing the tree

The left panel shows your project's file tree. Files are organized by folder, matching the structure on disk.

• Click a folder row to expand or collapse it.
• Click a filename to preview it in the File viewer.
• Filter by name using the search bar at the top of the tree. Only files and folders matching the query stay visible.
• Expand all / Collapse all buttons open or close every folder at once.

The sidebar is resizable — drag the handle on the right edge to adjust its width.

Keyboard shortcuts

Selecting files

Selection scopes your export and stats to just the files you care about. By default, with nothing selected, MashuPack operates on the full project.

• Tick a checkbox next to any file or folder to include it in your export. Ticking a folder selects everything inside it.
• Select All / Deselect All — buttons in the tree toolbar to quickly select or clear everything.
• File-type pills (shown in the "Select by type" row) — click a pill to toggle selection for all files of that extension at once. The pill highlights when all files of that type are selected.
• File types table in the right panel — click any row to toggle selection for all files of that type, same as the pills.

When you have a selection active, a SELECTION pill appears in the stats header, and all stats and export actions operate on your selection only. Click "Deselect all" to return to full-project mode.

Stats & the token toggle

The right panel shows live stats for the loaded project (or your selection, if active):

• Files — total file count in scope.
• Folders — total folder count.
• Size — total bytes of all files in scope. Click this stat to toggle between bytes and estimated token count. The token estimate uses a ~4 characters per token approximation, consistent with GPT and Claude tokenizers for typical code. Useful for sanity-checking before uploading to a model with a token limit.
• Root — the name of the loaded folder.

Below the summary stats:

• Composition bar — a color-coded proportional bar showing how each file type contributes to total project size. Hover a segment for the exact type and percentage.
• File types table — lists every extension found, with file count and size. The size column respects the bytes/tokens toggle. Click any row to select all files of that type.

Exporting

Three export actions are available in the top bar and report panel:

• Export combined text — downloads a single structured .txt file containing all files in scope (your selection, or the full project if nothing is selected). This is the main output for AI tools.
• Download .zip — downloads the full project as a ZIP archive, regardless of your selection. It is a separate action from the text export.
• Copy to clipboard — copies the current text report to your clipboard. Useful for pasting directly into an AI chat without saving a file.
• Save as .txt — saves the current text report as a .txt file. Same content as "Export combined text" but triggered from within the report panel.

The bottom status bar always shows how many files and how many bytes are currently in scope, so you can check the export size before downloading.

File viewer

Click any file in the tree to preview it in the File viewer tab. The viewer shows the file's contents with syntax highlighting (powered by CodeMirror), so you can read code without opening a separate editor.

Viewing a file in the preview does not include it in your export — inclusion is controlled entirely by checkboxes in the tree. The viewer is read-only and has no effect on what gets exported.

Switch between "Text report" and "File viewer" using the tabs above the main panel. The text report tab shows the full combined output for your current scope.

Export format

The exported file is plain text. It starts with a directory tree of the exported project, then each file wrapped in explicit START/END markers with its full path:

// ===== START OF FILE: src/app.ts ===== //
import { something } from "./lib";
...
// ===== END OF FILE: src/app.ts ===== //


// ===== START OF FILE: src/lib.ts ===== //
export function something() { ... }
// ===== END OF FILE: src/lib.ts ===== //

The START/END markers are what allow AI tools to grep, search, and navigate the export as a virtual project. Without them, the model sees one undifferentiated blob. With them, it can locate a specific file, read it, trace what it imports, and move on — the same way you would in a terminal.

The file is preceded by a directory tree showing the full structure of the exported project. This gives the AI a map before it reads any file contents.

Large repos

For most projects, MashuPack feels instant. For very large repositories — tens of thousands of files — the initial scan can take 10–20 seconds.

This time is spent on browser filesystem enumeration: your browser has to read the metadata for every file in the folder before MashuPack can build the tree. This is a browser-level operation and cannot be meaningfully sped up on MashuPack's end.

Once the scan is complete, everything else — browsing the tree, selecting files, filtering, exporting — is fast regardless of project size. MashuPack uses a virtualized tree renderer and Rust/WebAssembly for selection math, so even a 28,000-file repository navigates smoothly.

Tested with the kubernetes/kubernetes repository on a desktop browser. No backend. No upload.

Using the export with AI tools

The obvious objection: "stuffing a whole repo into an AI's context ruins its attention — the model can't reason over thousands of files."

That objection is correct for naive prompt dumps. But it misses how modern AI systems actually work.

Tools like ChatGPT and Claude don't just read uploaded files as raw context. They have internal environments where they can execute code, grep, search, and navigate structured text the same way a developer would in a terminal. When you upload a MashuPack export, the model can treat it as a virtual project — finding a function, tracing a dependency, or reading a specific file — without loading every byte into its attention window at once.

This is why the export format uses clear path headers and explicit file boundaries. The AI isn't reading the export like a wall of text. It's navigating it like a filesystem — and the headers are what make that navigation reliable.

How it's built

MashuPack is a static browser app — no server, no backend, no build pipeline on your end. It deploys as plain files on GitHub Pages and runs entirely client-side.

The part worth calling out: the indexing and selection math runs in Rust compiled to WebAssembly.

When you load a large project, there's real computation involved — building a tree from tens of thousands of file entries, calculating selection state, tracking which files are included, computing stats. Doing that on the browser's main thread would block rendering and make the UI feel sluggish. Rust/WASM behind a Web Worker keeps all of that compute off the main thread and genuinely fast, even at the scale of the Kubernetes repository.

The full stack:

• Rust + WebAssembly — tree construction, selection state, index math. Compiled with wasm-pack, runs in a Web Worker.
• TypeScript — all UI logic, event handling, filesystem coordination, export assembly.
• Vite — build tooling and dev server. Handles WASM imports cleanly via vite-plugin-wasm.
• File System Access API — the browser API that lets MashuPack read local folders without uploading them. Gives real directory handles with lazy file reading.
• Web Workers — the Rust/WASM engine runs in a Worker, keeping the main thread free for UI.
• Virtualized tree rendering — only the visible tree rows are in the DOM at any time. Scrolling through 28,000 files stays smooth because the browser isn't rendering 28,000 elements.
• CodeMirror — syntax-highlighted file preview in the File viewer tab.

The result is an app that handles repositories most browser tools would choke on, while still running as a simple static site you can open from a URL.