CodeCollector

Collect project code into LLM-ready Markdown. Select a directory, press Enter, copy and paste.

Installation

pipx (recommended)

brew install pipx
pipx ensurepath
pipx install onepaste

# Optional: exact token counting via tiktoken
pipx install "onepaste[tokens]"

Without the tokens extra, token counts use a fast characters/4 estimate.

From source (for development)

git clone https://github.com/emVisible/codecollector.git
cd codecollector
pipx install -e .

Uninstall / reinstall (for updates & debugging)

# Uninstall package
collect --uninstall

# Uninstall and remove ~/.config/codecollector
collect --uninstall --purge-config

# Reinstall editable from local source
cd /path/to/CodeCollector
pipx install -e .

Quick Start

# Interactive: navigate to folder → select "Collect this directory" → Enter
collect

# Collect current directory (.gitignore filtering on automatically inside git repos)
collect .

# Pipe straight into another tool — no file written
collect . --stdout | llm "Explain what this project does"

# Only TypeScript sources, skip tests
collect . --include "src/**/*.ts" --exclude-pattern "*.test.ts"

Output is a single Markdown file (code_collection.md) ready to copy-paste into any LLM.

Usage

# Interactive mode
collect
collect -i                    # force .gitignore filter (deprecated: auto inside git)

# Collect a specific directory
collect /path/to/project
collect . --no-gitignore      # include gitignored files too

# Non-recursive (current directory only)
collect . -n

# Custom output
collect . -o my_project.md
collect . -d ./collected

# Glob filtering (repeatable)
collect . --include "src/**"
collect . --include "*.py" --include "*.md"
collect . --exclude-pattern "*.min.js" --exclude-pattern "tests/*"

# Split large output (default: 2MB per part)
collect . --max-output-size 5

# Preview without writing
collect . --dry-run

# Extra exclusions
collect . --exclude vendor --exclude tmp

Options

.gitignore defaults

Inside a git work tree, .gitignore filtering is on by default. Outside git repos it is off. Explicit flags win over the default: -i forces it on, --no-gitignore forces it off. (-i used to be required to enable filtering; it still works but the default has changed.)

Glob patterns

--include / --exclude-pattern match against paths relative to the collected root using fnmatch semantics:

When --include patterns are given they replace the extension whitelist — you get exactly the matched files (still respecting excludes, size limits and binary detection).

Token counting

Summaries show total tokens plus per-file counts, with a Top-10 table of the largest files. With the optional tokens extra installed, counts are exact (tiktoken, o200k_base); otherwise an estimate (~4 chars/token) is shown and labelled as such.

Output Format

All output is detailed Markdown optimized for LLM consumption:

• Summary with metadata, token totals, top files by tokens, directory tree, and file list
• Each source file as a ### heading with line count, size, tokens, and a fenced code block (fences auto-lengthen so source containing backticks never breaks rendering)
• Auto-split into parts for large projects, each with Part X of N header

Output Behavior

Auto-increment (no overwrite)

If code_collection.md already exists, the next run writes to code_collection_1.md, then _2.md, etc.

Use --force to overwrite.

Auto-split

When output exceeds the size limit, files are split at source-file boundaries. A manifest JSON is written alongside multi-part output.

--stdout never splits; it warns on stderr if the limit would have been exceeded. It also requires an explicit path — the interactive picker would otherwise mix its own output into the piped stream.

Configuration

collect --init-config

Edit ~/.config/codecollector/config.json:

{
  "exclude_dirs": [
    "node_modules",
    ".git",
    "__pycache__",
    "venv",
    "dist",
    "build"
  ],
  "include_extensions": [".py", ".js", ".ts", ".go", ".rs", ".java"],
  "include_patterns": [],
  "exclude_patterns": [],
  "max_file_size_mb": 5.0,
  "max_output_size_mb": 2.0,
  "auto_increment_output": true,
  "write_manifest": true
}

.gitignore filtering is intentionally not stored in the config file — it resolves automatically per run (on inside git work trees) unless overridden by -i or --no-gitignore.

Requirements

• Python 3.8+
• pipx (for installation)