concat-glob-tool
Concatenate files with intelligent separators

A CLI tool that concatenates files matching glob patterns with intelligent separators and agent-friendly design.
Table of Contents
About
concat-glob-tool is a CLI-first utility that concatenates multiple files into a single output file with intelligent separators. Built with modern Python tooling and designed for both human use and AI agent integration.
What is concat-glob-tool?
concat-glob-tool provides a simple yet powerful way to combine multiple files into a single file with clear separators between each file. It's particularly useful for:
- Creating context files for Large Language Models (LLMs)
- Combining source code for documentation or analysis
- Aggregating log files or configuration files
- Building single-file distributions
Why CLI-First?
This tool follows a CLI-first design philosophy, making it:
- 🤖 Agent-Friendly: Designed for AI agents (Claude Code) with structured commands, clear error messages, and working examples in help text
- 🔗 Composable: JSON output to stdout, logs to stderr for easy piping and integration with automation tools
- 🧱 Reusable: Commands serve as building blocks for Claude Code skills, MCP servers, shell scripts, or custom workflows
- ✅ Reliable: Type-safe with comprehensive testing ensures predictable behavior in automated systems
- 📚 Self-Documenting: Rich help messages guide both humans and agents through usage patterns
- 🔧 Maintainable: Modular architecture makes it easy to extend, debug, and evolve
Dual-Mode Operation
- CLI Mode: Use as a standalone command-line tool with all features
- Library Mode: Import core functions for programmatic integration in Python scripts
Use Cases
- 📚 LLM Context Generation: Combine multiple source files into a single context file for feeding to Large Language Models
- 💻 Code Documentation: Aggregate source code files for documentation or code review
- 🔍 Log Analysis: Merge multiple log files with clear file separators for easier analysis
- 📦 Single-File Distribution: Create self-contained bundles of configuration or template files
- 🎯 RAG Preparation: Prepare documents for Retrieval-Augmented Generation systems
- 🤖 Agent Integration: Build reusable file processing pipelines for AI automation workflows
Features
- 🎯 Glob Pattern Matching: Support for multiple glob patterns including recursive patterns (
**/*.py)
- 📥 Stdin Support: Read file paths from stdin for integration with other tools (e.g.,
find)
- 🔀 Intelligent Separators: Files are separated with headers including the filename
- 🔍 Dry-Run Mode: Preview operations before execution (enabled by default)
- 💪 Force Overwrite: Safely overwrite existing files with explicit flag
- 🎨 Custom Separators: Configurable separator text between files
- ✅ Type-safe with mypy strict mode
- ✅ Linted with ruff
- ✅ Tested with pytest
- 📊 Multi-level verbosity logging (-v/-vv/-vvv)
- 🐚 Shell completion for bash, zsh, and fish
- 🔒 Security scanning with bandit, pip-audit, and gitleaks
- ✅ Modern Python tooling (uv, mise, click)
- 📦 Dual-mode: CLI tool + importable Python library
Installation
Prerequisites
- Python 3.14 or higher
- uv package manager
Install from source
# Clone the repository
git clone https://github.com/dnvriend/concat-glob-tool.git
cd concat-glob-tool
# Install globally with uv
uv tool install .
Install with mise (recommended for development)
cd concat-glob-tool
mise trust
mise install
uv sync
uv tool install .
Verify installation