Combicode

Combicode is a CLI tool that intelligently combines your project's source code into a single, LLM-friendly text file with an expanded code map showing classes, functions, and loops with precise line references.

The generated file starts with a system prompt and an expanded tree structure that shows not just files, but also the code elements inside them (classes, functions, loops) with their line numbers and sizes. This gives the LLM a complete mental model of your codebase architecture before it reads a single line of code.

Table of Contents

• Why use Combicode?
• Quick Start
• Supported Languages
• Usage and Options
• All CLI Options
• How the Code Map Works
• Examples
• License

Why use Combicode?

| Feature | Description | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | | 🗺️ Expanded Code Map | Shows classes, functions, and loops with line numbers and sizes - LLMs understand your architecture instantly | | 🎯 Precise Navigation | Every element has [OL: X-Y \| ML: X-Y \| SIZE] references for both original and merged line numbers | | 📦 Maximum Context | Gives your LLM a complete picture of your project structure and code | | 🌍 40+ Languages | Python (AST-based), JavaScript, TypeScript, Go, Rust, Java, C/C++, C#, PHP, Ruby, Swift, Kotlin, Scala, and more | | 🧹 Intelligent Ignoring | Automatically skips node_modules, .venv, dist, .git, binary files, and other common junk | | 📝 .gitignore Aware | Respects your project's existing .gitignore rules out of the box | | 📁 Nested Ignore Support | Correctly handles .gitignore files located in subdirectories | | ⚡ Zero-Install Usage | Run it directly with npx or pipx without polluting your environment | | 🔄 Recreate Support | Extract files from combicode.txt back to original project structure |

Quick Start

Navigate to your project's root directory in your terminal and run one of the following commands:

For Node.js/JavaScript/TypeScript projects (via npx)

npx combicode

For Python projects (via pipx)

pipx run combicode

This will create a combicode.txt file in your project directory with the expanded code map.

Supported Languages

Combicode parses code structure for 40+ programming languages:

Full Language Support Table

| Language | Parser | Elements Detected | | ---------- | -------------- | ------------------------------------------------------ | | Python | AST (built-in) | class, def, async def, for, while | | JavaScript | Regex | class, function, async function, arrow functions | | TypeScript | Regex | class, interface, function, async function | | Go | Regex | struct, interface, func | | Rust | Regex | struct, enum, trait, impl, fn | | Java | Regex | class, interface, enum, methods | | C/C++ | Regex | class, struct, functions | | C# | Regex | class, struct, interface, enum, record | | PHP | Regex | class, interface, trait, function | | Ruby | Regex | class, module, def | | Swift | Regex | class, struct, enum, protocol, func | | Kotlin | Regex | class, interface, object, fun | | Scala | Regex | class, object, trait, def | | Lua | Regex | function, local function | | Perl | Regex | sub, package | | Bash | Regex | function, for, while |

Configuration Files (No Parsing)

These files are included in the tree but not parsed for code structure:

| Type | Extensions | | ------ | ------------------------------------------------- | | Config | .json, .yaml, .yml, .toml, .ini, .env | | Markup | .md, .rst, .txt | | Styles | .css, .scss, .less, .sass |

Usage and Options

Preview which files will be included

Use the --dry-run or -d flag to see a list of files without creating the output file.

npx combicode --dry-run
pipx run combicode -d

Example output:

✨ Combicode v2.0.0

📂 Root: /home/user/my-project

📋 Files to include (dry run):

   src/index.ts (2.1KB)
   src/server.ts (3.4KB)
   src/utils/db.ts (1.2KB)
   package.json (0.8KB)
   tsconfig.json (0.3KB)

📊 Summary:
   • Total files: 5
   • Total size: 7.8KB

✅ Done!

Specify an output file

Use the --output or -o flag.

npx combicode -o my_project_context.md
pipx run combicode --output ./output/context.txt

Include only specific file types

Use the --include-ext or -i flag with a comma-separated list of extensions.

# Include only TypeScript, TSX, and CSS files
npx combicode -i .ts,.tsx,.css

# Include only Python and YAML files
pipx run combicode -i .py,.yaml

# Include only markdown documentation
npx combicode -i .md -o llms.txt

Add custom exclude patterns

Use the --exclude or -e flag with comma-separated glob patterns.

# Exclude all test files and anything in a 'docs' folder
npx combicode -e "**/*_test.py,docs/**"

# Exclude generated files and fixtures
pipx run combicode -e "**/*.generated.*,fixtures/**"

Skip content for specific files

Use the --skip-content flag to include files in the tree structure but omit their content. This is useful for large files (like test files) that you want visible in the project overview but don't need their full content.

# Include .test.ts files in tree but skip their content
npx combicode --skip-content "**/*.test.ts"

# Skip content for multiple patterns
npx combicode --skip-content "**/*.test.ts,**/*.spec.ts,**/tests/**"

# Skip large generated files
pipx run combicode --skip-content "**/*.min.js,dist/**"

Output with skipped content:

└── tests/
    └── test_server.py [OL: 1-450 | ML: 183-184 | 12.1KB]
        (Content omitted - file size: 12.1KB)

Disable code structure parsing

Use the --no-parse flag to generate a simple file tree without parsing classes, functions, or loops. This is useful for quick overviews or when parsing is not needed.

npx combicode --no-parse

Output with --no-parse:

<code_index>
project-root/
├── src/
│   ├── server.py [OL: 1-85 | ML: 53-137 | 2.4KB]
│   └── utils/
│       └── db.py [OL: 1-45 | ML: 138-182 | 1.2KB]
└── tests/
    └── test_server.py [OL: 1-50 | ML: 183-232 | 1.1KB]
</code_index>

Generating Context for llms.txt

The --llms-txt or -l flag is designed for projects that use an llms.txt file to specify important documentation.

# Combine all markdown files for an llms.txt context
npx combicode -l -i .md -o llms.txt

# Combine documentation from docs folder
pipx run combicode -l -i .md,.rst -o llms.txt

Recreate Project from combicode.txt

The --recreate or -r flag extracts all files from a combicode.txt file and recreates the original project structure. This is useful for:

• 🔄 Restoring a project from an LLM-generated context
• 📤 Extracting code shared by others in combicode.txt format
• 🛠️ Converting the merged file back to individual source files

# Recreate project from combicode.txt (default)
npx combicode --recreate

# Specify input file and output directory
npx combicode --recreate --input my_context.txt -o ./restored_project

# Short form
npx combicode -r -i my_context.txt -o ./output

# Dry run to see what files would be extracted
npx combicode --recreate --dry-run

# Overwrite existing files
npx combicode --recreate --overwrite

Example output:

✨ Combicode v2.0.0

📂 Root: /home/user/projects

📂 Output directory: /home/user/projects

   src/index.ts (2.1KB)
   src/server.ts (3.4KB)
   src/utils/db.ts (1.2KB)
   src/utils/logger.ts (0.8KB)
   src/handlers/user.ts (1.5KB)
   src/handlers/auth.ts (1.2KB)
   config/app.yaml (0.4KB)
   package.json (0.8KB)
   tsconfig.json (0.3KB)
   ...

📊 Summary:
   • Files recreated: 15
   • Total size: 45.2KB

✅ Done!

All CLI Options

| Option | Alias | Description | Default | | ---------------- | ----- | ------------------------------------------------------------------------------ | --------------- | | --output | -o | Output file (combine) or directory (recreate). | combicode.txt | | --dry-run | -d | Preview without making changes. | false | | --include-ext | -i | Comma-separated list of extensions to exclusively include. | (include all) | | --exclude | -e | Comma-separated list of additional glob patterns to exclude. | (none) | | --skip-content | | Comma-separated glob patterns for files to include in tree but omit content. | (none) | | --no-parse | | Disable code structure parsing (show only file tree). | false | | --llms-txt | -l | Use a specialized system prompt for context generated from an llms.txt file. | false | | --no-gitignore | | Do not use patterns from the project's .gitignore file. | false | | --no-header | | Omit the introductory prompt and file tree from the output. | false | | --recreate | -r | Recreate project from a combicode.txt file. | false | | --input | | Input combicode.txt file for recreate. | combicode.txt | | --overwrite | | Overwrite existing files when recreating. | false | | --version | -v | Show the version number. | | | --help | -h | Show the help message. | |

How the Code Map Works

Line Reference System

Every element has dual line references:

| Reference | Description | Usage | | ---------------------- | ------------------------------------------------- | ------------------------------- | | OL (Original Line) | Line numbers in the source file on disk | Find code in original project | | ML (Merged Line) | Line numbers in the combined combicode.txt file | Extract code with sed command |

Extracting code using ML:

# Extract lines 100-150 from combicode.txt
sed -n '100,150p' combicode.txt

# Extract a specific function
sed -n '69,97p' combicode.txt  # Extracts async start() method

Element Types

The code map extracts these element types:

| Label | Description | Example | | ---------- | ------------------------------------------- | -------------------------------- | | class | Classes, structs, interfaces, enums, traits | class Server | | fn | Functions and methods | fn parse_args() | | async | Async functions | async fetch_data() | | ctor | Constructors (__init__, constructor) | ctor __init__(self, port: int) | | loop | For/while loops (only if > 5 lines) | loop for item in items | | impl | Implementation blocks (Rust) | impl Server | | test | Test functions | test test_server_start | | describe | Test suites | describe Server |

Filtering Rules

| Category | Elements | | -------------------------- | -------------------------------------------------------- | | Always included | Files, classes, functions, constructors | | Conditionally included | Loops and try/catch blocks (only if > 5-10 lines) | | Excluded | Imports, comments, single-line elements, getters/setters |

Examples

Python Project

src/
├── main.py [OL: 1-85 | ML: 53-137 | 2.4KB]
│   ├── class Server [OL: 5-60 | ML: 57-112 | 1.8KB]
│   │   ├── ctor __init__(self, host: str, port: int) [OL: 7-15 | ML: 59-67 | 284B]
│   │   ├── async start(self) -> None [OL: 17-45 | ML: 69-97 | 892B]
│   │   └── fn stop(self) -> None [OL: 47-55 | ML: 99-107 | 256B]
│   └── fn parse_args() -> dict [OL: 63-85 | ML: 115-137 | 612B]
├── utils/
│   └── db.py [OL: 1-45 | ML: 138-182 | 1.2KB]
│       └── class Database [OL: 5-40 | ML: 142-177 | 1.1KB]
│           ├── ctor __init__(self, connection_string: str) [OL: 7-15 | ML: 144-152 | 312B]
│           └── fn query(self, sql: str) -> list [OL: 17-40 | ML: 154-177 | 756B]
└── config.py [OL: 1-20 | ML: 183-202 | 0.4KB]

TypeScript Project

src/
├── index.ts [OL: 1-52 | ML: 53-104 | 2.1KB]
│   ├── class Server [OL: 5-42 | ML: 57-94 | 1.5KB]
│   │   ├── ctor (port: number, host?: string) [OL: 7-14 | ML: 59-66 | 256B]
│   │   ├── async start(): Promise<void> [OL: 16-32 | ML: 68-84 | 612B]
│   │   └── fn stop(): void [OL: 34-42 | ML: 86-94 | 298B]
│   └── fn createApp(config: Config): Express [OL: 45-52 | ML: 97-104 | 412B]
├── handlers/
│   └── user.ts [OL: 1-78 | ML: 105-182 | 2.4KB]
│       ├── interface UserRoutes [OL: 5-15 | ML: 109-119 | 312B]
│       └── fn createUser(req: Request, res: Response) [OL: 17-78 | ML: 121-182 | 1.8KB]
└── types/
    └── index.ts [OL: 1-25 | ML: 183-207 | 0.5KB]
        └── interface Config [OL: 3-25 | ML: 185-207 | 456B]

Go Project

cmd/
└── server/
    └── main.go [OL: 1-60 | ML: 53-112 | 1.6KB]
        └── fn main() [OL: 5-60 | ML: 57-112 | 1.4KB]

internal/
├── handlers/
│   └── user.go [OL: 1-120 | ML: 113-232 | 3.2KB]
│       ├── struct UserHandler [OL: 8-25 | ML: 120-137 | 512B]
│       └── fn NewUserHandler(db *sql.DB) *UserHandler [OL: 27-35 | ML: 139-147 | 234B]
└── models/
    └── user.go [OL: 1-45 | ML: 233-277 | 1.1KB]
        └── struct User [OL: 5-45 | ML: 237-277 | 945B]

Rust Project

src/
├── main.rs [OL: 1-45 | ML: 53-97 | 1.2KB]
│   └── fn main() [OL: 3-45 | ML: 55-97 | 1.0KB]
├── server/
│   └── mod.rs [OL: 1-120 | ML: 98-217 | 3.4KB]
│       ├── struct Server [OL: 5-25 | ML: 102-122 | 612B]
│       ├── impl Server [OL: 27-100 | ML: 124-197 | 2.5KB]
│       │   ├── fn new(host: &str, port: u16) -> Self [OL: 29-45 | ML: 126-142 | 456B]
│       │   └── async fn start(&self) -> Result<()> [OL: 47-100 | ML: 144-197 | 1.8KB]
│       └── fn create_server(config: Config) -> Server [OL: 102-120 | ML: 199-217 | 534B]
└── config.rs [OL: 1-35 | ML: 218-252 | 0.8KB]
    └── struct Config [OL: 3-35 | ML: 220-252 | 712B]

Java Project

src/main/java/com/example/
├── Application.java [OL: 1-30 | ML: 53-82 | 0.9KB]
│   └── class Application [OL: 3-30 | ML: 55-82 | 756B]
│       └── fn main(String[] args) [OL: 5-30 | ML: 57-82 | 654B]
├── server/
│   └── Server.java [OL: 1-150 | ML: 83-232 | 4.2KB]
│       ├── class Server [OL: 5-120 | ML: 87-202 | 3.4KB]
│       │   ├── ctor Server(int port, String host) [OL: 15-35 | ML: 97-117 | 612B]
│       │   ├── fn start() [OL: 37-80 | ML: 119-162 | 1.2KB]
│       │   └── fn stop() [OL: 82-120 | ML: 164-202 | 1.1KB]
│       └── class ServerBuilder [OL: 122-150 | ML: 204-232 | 756B]
└── config/
    └── Config.java [OL: 1-45 | ML: 233-277 | 1.1KB]
        └── class Config [OL: 3-45 | ML: 235-277 | 1.0KB]

License

This project is licensed under the MIT License.