A CLI tool to recursively scan a directory, concatenate file contents, and copy them to the clipboard.
npm install context-copyccopy)context-copy is a powerful and configurable command-line tool that recursively scans a project directory, concatenates the contents of relevant files into a single string, and copies it to your clipboard.It's designed to make it easy to grab the entire context of a codebase for use in Large Language Models (LLMs) like GPT-4, Claude, or Gemini.
- Recursive Directory Scanning: Scans an entire project directory from the root.
- Smart Ignoring: Automatically ignores common unnecessary files and directories (like node_modules, .git, build artifacts, and binaries).
- .gitignore Integration: Automatically respects rules found in your project's .gitignore files.
- Custom Ignore Rules: Supports a .contextignore file for project-specific rules that shouldn't be in .gitignore.
- Single File Mode: Can be pointed at a single file for quick copying.
- Smart Import Following: When pointing to a single file, can optionally follow and copy all local imported files (--follow-imports).
- Alias Aware: Understands jsconfig.json/tsconfig.json path aliases (e.g., @/*).
- Deep/Shallow Mode: Control import following to be "shallow" (direct imports only) or "deep" (recursive).
- Informative Output: Displays a tree of copied files and color-coded stats on the context size.
- Clipboard Integration: Copies the final formatted context directly to your system's clipboard.
- Alias: Comes with a convenient ccopy alias for quicker use.
You can install context-copy globally using npm, which will make the context-copy and ccopy commands available in your terminal.
``bash`
npm install -g context-copy
---
The command is simple and intuitive. You can use either context-copy or the shorter ccopy alias.
To copy the current directory, simply run:
`bash`
ccopy
Or target a specific directory:
`bash`
ccopy /path/to/your/project
You can pass a path to a single file. For more advanced context gathering, use the import following options.
To copy src/main.js and all direct local files it imports (shallow copy):
`bash`
ccopy src/main.js --follow-imports
To recursively copy all imports (imports of imports, etc.):
`bash`
ccopy src/main.js --follow-imports --deep
You can invert the logic from _ignoring_ files to _only including_ files that match specific glob patterns. This is useful for grabbing a specific slice of a project.
`bashOnly copy .js files from the 'src/components' directory
ccopy --only "src/components/*/.js"
---
⚙️ Persistent Configuration
includes a config command to save persistent settings locally. This allows you to set your favorite defaults (like --prepend-tree) once, so you don't have to type them in every time.Settings are saved to a JSON file in your home directory (e.g.,
~/.context-copy/config.json).$3
- List current settings:
`bash
ccopy config list
` This will show all your saved settings and the path to the config file. If no settings are saved, it will say so.
- Set a default value:
This is the primary command you'll use.
bash
# Always include the file tree by default
ccopy config set prepend-tree true # Always use a different ignore file name
ccopy config set ignore-file .my-special-ignore
` The tool understands boolean strings like "true" and "false".
- Get a specific value:
bash
ccopy config get prepend-tree
` This will output
(or whatever value is saved, or a default message if not set).- Edit the raw config file:
For power-users, you can open the
config.json file directly in your default editor.
`bash
ccopy config edit
`
This will try to use , nano, or notepad depending on your system.$3
You can set defaults for the following keys, which correspond to the main command-line flags:
-
prepend-tree
-
-
-
- $3
Command-line flags always win. Any flag you provide in a command (e.g.,
) will override your saved default for that single run.---
Command Options
| Option | Alias | Argument | Description | Default |
| :----------------- | :---- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |
|
--ignore-file | -i | | Path to a custom ignore file, like a .contextignore. Rules in this file are merged with defaults and .gitignore. | .contextignore |
| --follow-imports | -f | | When used with a single file, it enables tracing and including local imports (relative and aliased) into the context. | Off (Directory Scan) |
| --deep | -d | | Recursively follow imports (imports of imports, up to $\text{Infinity}$ depth). This option requires --follow-imports to be active. | Off (Shallow Trace) |
| --prepend-tree | -p | | Prepends the text-based file tree structure to the copied context. | Off |
| --output | -o | | Save the context to a specified file instead of copying to the clipboard. | Off |
| --only | | | Only include files matching the glob pattern. Can be used multiple times. Inverts scan to be additive. | Off (Full Scan) |
| --debug | -D | | Enable verbose debugging output (internal logs, import resolution, ignored-file decisions, and stack traces). | Off |
| --version | -V | | Output the version number. | |
| --help | -h | | Display help for command. | |---
How It Works
1. Scan: The tool starts at the specified path (or the current directory).
2. Ignore: It gathers a list of ignore patterns from its own sensible defaults, any
.gitignore files it finds, and an optional custom ignore file (.contextignore by default).
3. Read: It reads the contents of every file that is not ignored.
- Import Following: If run on a single file with --follow-imports, it parses the file, resolves local/aliased imports, and adds them to a queue to be read.
4. Format: It concatenates the contents, adding a header before each file's content (e.g., === File: src/main.js ===`).