concat-glob-tool

concat-glob-tool

A CLI tool that concatenates files matching glob patterns with intelligent separators and agent-friendly design.

Table of Contents

• About
• Use Cases
• Features
• Installation
• Configuration
• Usage
• Library Usage
• Multi-Level Verbosity Logging
• Shell Completion
• Development
• Testing
• Security
• Contributing
• License
• Author

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