简体中文

Codefuse is an LLM-ready code snapshot CLI for merging project source files, reducing token footprint, and keeping the result easy to share in AI conversations.

It combines three workflows in one tool:

• merge: merge many source files into one clean text snapshot
• tree: export a readable directory tree
• restore: rebuild files from a merged snapshot

The main goal of Codefuse is not generic archiving or build optimization.

Its primary purpose is to:

• merge a project's source files into one shareable snapshot
• reduce token usage as much as practical for LLM conversations
• keep enough structure so the snapshot is still readable and restorable

In practice, that means merge is the core workflow, while tree and restore support the same snapshot-sharing loop.

The project is designed to be:

• easy to install from a Git repository with npm
• friendly to Bun binary builds
• free of runtime dependencies like minimatch

• JSON-based workflow with init and run
• one config can run multiple tasks in sequence
• built-in comment stripping and whitespace compaction to cut token noise
• supports merge, restore, and tree export out of the box
• works with Node.js at runtime, Bun only for building binaries

Install globally from the GitHub source tarball:

npm install -g https://github.com/rurico/codefuse/archive/refs/heads/main.tar.gz

Install it locally in a project from the Git repository:

npm install git+https://github.com/rurico/codefuse.git
npx codefuse init

For local development:

npm install
npm test

• Global install: prefer the GitHub tarball URL above
• Project-local install: npm install git+https://github.com/rurico/codefuse.git works well, then run with npx codefuse
• On some npm setups, npm install -g git+https://... may leave a broken temporary symlink instead of a stable package directory

If you already hit that broken global install case, the repair commands are:

PREFIX="$(npm prefix -g)"
rm -f "$PREFIX/bin/codefuse"
rm -rf "$PREFIX/lib/node_modules/codefuse"
npm install -g https://github.com/rurico/codefuse/archive/refs/heads/main.tar.gz

Generate a config file:

codefuse init

Edit codefuse.config.jsonc, then run:

codefuse run

You can also point to a custom config path:

codefuse init ./configs/project.jsonc
codefuse run ./configs/project.jsonc

An example config is available at examples/codefuse.config.example.jsonc.

codefuse init [config-path] [--force]
codefuse run [config-path]
codefuse [config-path]
codefuse help [merge|tree|restore|config|examples|all]

• codefuse init: create a starter JSON config
• codefuse run: execute enabled tasks from a config file
• codefuse <config-path>: shorthand for run
• codefuse help ...: show focused help for one topic

codefuse --help
codefuse help config
codefuse help merge
codefuse help tree
codefuse help restore
codefuse help examples

Each config contains a tasks array. Enabled tasks run in order.

{
 "version": 1,
 "tasks": [
 {
 "name": "merge-source",
 "type": "merge",
 "enabled": true
 }
 ]
}

• tasks run in array order
• tasks with "enabled": false are skipped
• one config can contain multiple task types
• relative paths are resolved from the config file location

{
 "name": "merge-source",
 "type": "merge",
 "enabled": true,
 "source": "./",
 "output": "./artifacts/merged_output_clean.txt",
 "patterns": ["**/*.ts", "**/*.tsx"],
 "exclude": [],
 "stripComments": true,
 "compactWhitespace": true
}

Field notes:

• source: root directory to scan
• output: merged snapshot path
• patterns: include globs; if omitted, Codefuse uses the built-in source file set
• exclude: extra exclude globs in addition to built-in ignores
• stripComments: remove comments by language to reduce token noise
• compactWhitespace: remove blank lines and trailing spaces to reduce snapshot size
• concurrency: optional parallel file processing count
• verbose: optional per-file logging switch, off by default

{
 "name": "tree-source",
 "type": "tree",
 "enabled": true,
 "source": "./",
 "output": "./artifacts/directory_tree.txt",
 "exclude": []
}

Field notes:

• source: root directory to scan
• output: where the tree text will be written
• exclude: extra exclude globs
• rootLabel: optional display label for the root node

{
 "name": "restore-snapshot",
 "type": "restore",
 "enabled": true,
 "input": "./artifacts/merged_output_clean.txt",
 "outputRoot": "./restored"
}

Field notes:

• input: a merged snapshot created by merge
• outputRoot: directory where files will be recreated
• restore only writes inside outputRoot

{
 "version": 1,
 "tasks": [
 {
 "name": "merge-source",
 "type": "merge",
 "enabled": true,
 "source": "./",
 "output": "./artifacts/merged_output_clean.txt"
 }
 ]
}

{
 "version": 1,
 "tasks": [
 {
 "name": "tree-source",
 "type": "tree",
 "enabled": true,
 "source": "./",
 "output": "./artifacts/directory_tree.txt"
 },
 {
 "name": "merge-source",
 "type": "merge",
 "enabled": true,
 "source": "./",
 "output": "./artifacts/merged_output_clean.txt"
 }
 ]
}

{
 "version": 1,
 "tasks": [
 {
 "name": "restore-snapshot",
 "type": "restore",
 "enabled": true,
 "input": "./artifacts/merged_output_clean.txt",
 "outputRoot": "./restored"
 }
 ]
}

stripComments and compactWhitespace are snapshot options, not production minification.

• stripComments removes comments so the merged output spends fewer tokens on non-essential explanation
• compactWhitespace removes blank lines and trailing whitespace so the snapshot is smaller and cheaper to send to an LLM
• neither option renames variables, rewrites logic, or turns code into a one-line blob

If you want the merged output to stay closer to the original source layout, set either option to false.

The merge task writes a text snapshot in this structure:

File: src/index.ts
```typescript
export const value = 1;
```

That output format is what restore reads back when rebuilding files.

Build with Bun:

bun run build

The compiled binary will be written to dist/codefuse.

• Runtime: Node.js 22+
• Build tool: Bun 1.3+
• Test command: npm test

• GitHub: rurico/codefuse
• Issues: github.com/rurico/codefuse/issues

Please read CONTRIBUTING.md before opening a pull request.

MIT