list-codes - Source Code Analysis Assistant for LLMs

🎯 About This Tool

list-codes is a command-line tool designed to collect and format source code from a specified project, making it easy to analyze with Large Language Models (LLMs).

Its main purpose is to output the source code of an entire project or a specific directory as a single text, which can be copied and pasted into an LLM's prompt to streamline tasks like code reviews, documentation generation, and bug detection.

🚀 Primary Use Case: LLM Integration

The output of this tool is intended to be used directly as input for an LLM.

Terminal Commands

# Copy the entire project's source code to the clipboard and paste it into an LLM
list-codes /path/to/your/project | pbcopy

# Request a code review using predefined template
list-codes --prompt refactor ./src/feature | llm-cli

# Generate a project overview using predefined template
list-codes --prompt explain . > project_overview.txt

# Use custom prompt text
list-codes --prompt "Analyze this code for security vulnerabilities and provide recommendations" ./src

# Use custom prompt in Japanese
list-codes --prompt "このコードの性能問題を特定して改善案を提示してください" ./src

You can ask the LLM to perform tasks such as:

Understanding a new project: Quickly grasp the overall picture and architecture.
Code review: Get feedback on bugs, security vulnerabilities, and performance issues.
Refactoring suggestions: Receive ideas for cleaner and more efficient code.
Documentation generation: Create drafts for READMEs and specifications.
Test ideas: Brainstorm test cases to improve coverage.

✨ Key Features

📁Source Code Collection

Recursively collects source code from the specified directory. It automatically respects .gitignore to exclude unnecessary files like node_modules.

🔧Flexible Filtering

Use --exclude and --include options with powerful glob pattern support. Non-recursive patterns like *.md are anchored to root, while **/*.md matches recursively throughout your project. Override defaults with explicit includes.

📊Smart File Size Management

Configure file and total size limits with human-readable formats (e.g., 1m, 500k, 2g) to control output size and processing time.

🤖LLM-Ready Prompts

The --prompt option allows you to prepend either predefined templates (e.g., explain, find-bugs) or your own custom prompt text to make your instructions to the LLM simple and precise.

🧪Test File Control

Automatically excludes test files by default, with --include-tests option to include them when needed for comprehensive analysis.

📄YAML Config File

Persist your include/exclude patterns and options in a .list-codes.yaml config file. Auto-loaded from project root, with CLI flags taking priority.

🎨Interactive File Selector

Use list-codes select to open a TUI for browsing your project tree and toggling file selection. Saves results as a reusable config file.

🎯Structured Output

Generates organized Markdown with Source Code Size Check, Project Structure, Source Files, and Configuration sections in logical order.

Filtering and Exclusion Behavior

list-codes provides powerful filtering capabilities with glob pattern support, automatic exclusions, and a clear priority system to give you precise control over which files are included in your code analysis.

Automatic Exclusions

The tool automatically excludes certain files and directories to focus on relevant source code:

Dotfiles and Dot-directories

All files and directories starting with a dot (.) are excluded by default:

.git, .gitignore, .github/
.vscode/, .idea/
.env, .DS_Store
.terraform/, .serverless/
.pytest_cache/, .mypy_cache/

Build and Dependency Directories

Common build artifacts and dependency directories are excluded:

node_modules/, vendor/, target/
build/, dist/, __pycache__/
env/, venv/

Gitignore Integration

Automatically respects your project's .gitignore rules:

Hierarchical processing with proper precedence
Full pattern support (wildcards, negation)
Override with --include flag
Disable with --no-gitignore option

Glob Pattern Anchoring ⭐

Critical behavior: Both --include and --exclude flags support glob patterns with automatic anchoring behavior:

Non-recursive Patterns (Anchored to Root)

# *.md - Matches .md files ONLY in the project root (non-recursive)
list-codes --exclude "*.md"

# src/*.ts - Matches .ts files only inside the src directory (not subdirectories)
list-codes --include "src/*.ts"

Recursive Patterns (Use **)

# **/*.md - Matches .md files recursively in all directories
list-codes --exclude "**/*.md"

# src/**/*.ts - Matches .ts files recursively within src and subdirectories
list-codes --include "src/**/*.ts"

Exclusion Priority System

The filtering logic follows a clear 4-level priority hierarchy:

1️⃣ Explicit Exclusions (Highest Priority)

--exclude flags always win, even inside explicitly included folders. This allows recursive exclusion within included paths.

2️⃣ Include Whitelist

--include flags override default dotfile exclusion and .gitignore rules. Only whitelisted paths are processed when includes are specified.

3️⃣ Gitignore Rules

Project .gitignore patterns are respected unless overridden by --include. Nested gitignore files are processed with proper precedence.

4️⃣ Default Exclusions

Built-in exclusions for dotfiles, node_modules, vendor, build directories apply if not explicitly included.

📚 Practical Filtering Examples ▼

Example 1: Exclude Root Markdown Files Only

# Excludes README.md, CHANGELOG.md in root, but keeps docs/guide.md
list-codes --exclude "*.md"

Example 2: Exclude All Markdown Files Recursively

# Excludes all .md files throughout the entire project
list-codes --exclude "**/*.md"

Example 3: Include Directory with Recursive Exclusion

# Include src directory but exclude the secret subdirectory within it
list-codes --include "src" --exclude "src/secret"

Example 4: Override Dotfile Exclusion

# Include .github directory (normally excluded as a dotfile)
list-codes --include ".github/**"

Example 5: Exclude Tests but Include CI Workflows

# Exclude all test files but include .github workflows
list-codes --exclude "**/*test*" --include ".github/workflows/**"

Example 6: Target Specific File Types in Subdirectory

# Include only TypeScript files within components directory and subdirectories
list-codes --include "components/**/*.ts"

🛠️ Installation and Usage

Installation

Option 1: Homebrew (macOS/Linux) - Recommended

Homebrew Installation

brew tap luckpoint/list-codes
brew install list-codes

Option 2: Go Install

Go Installation

go install github.com/luckpoint/list-codes/cmd/list-codes@latest

Note: You need to have $GOPATH/bin (or $HOME/go/bin) in your system's PATH.

Option 3: Download Binary

Download the latest binary for your platform from the releases page.

Option 4: Build from Source

Build from Source

git clone https://github.com/luckpoint/list-codes.git
cd list-codes
go build -o list-codes ./cmd/list-codes

Basic Usage

Basic Commands

# Display the source code of the current directory to standard output
list-codes

# Specify a project folder
list-codes --folder /path/to/your/project

# Target only the `src` and `pkg` directories
list-codes --include "src/**,pkg/**"

# Exclude `*.test.go` files
list-codes --exclude "**/*.test.go"

# Add a predefined template and output to a file
list-codes --prompt explain --output for_llm.txt

# Use custom prompt text
list-codes --prompt "Review this code for accessibility issues" --output review.txt

# Control file size limits with human-readable formats
list-codes --max-file-size 500k --max-total-size 10m

# Include test files in the analysis
list-codes --include-tests

# Enable debug mode and force language
list-codes --debug --lang en

# Show version information
list-codes --version

Command-Line Options

Available Options

# Core options
--folder, -f      Folder to scan (default: current directory)
--output, -o      Output Markdown file path
--prompt, -p      Prompt text or template name to prepend to output

# Filtering options
--include, -i     File/folder path to include, overrides default exclusions (repeatable, supports glob patterns)
--exclude, -e     File/folder path to exclude, takes highest priority (repeatable, supports glob patterns)
--readme-only     Only collect README.md files
--max-file-size   Maximum file size (supports 1m, 500k, 2g) (default: 1m)
--max-total-size  Maximum total file size (supports 10m, 1g) - empty means no limit
--max-depth       Max depth for directory structure (default: 7)
--include-tests   Include test files in the output (excluded by default)

# Configuration options
--config, -c      Config file path (.list-codes.yaml)
--no-config       Disable auto-loading .list-codes.yaml

# Other options
--debug           Enable debug mode
--lang            Force language (ja|en) instead of auto-detection
--version, -v     Show version information
--help, -h        Show help message

# Subcommands
select            Open TUI to interactively select files and save config

🎯 Prompt Templates and Custom Prompts

The --prompt option allows you to prepend specialized prompts to your code output, making it easier to get targeted analysis from LLMs.

Predefined Templates

list-codes includes a comprehensive set of predefined prompt templates for common analysis tasks:

Core Analysis

explain - Project overview and architecture
find-bugs - Bug detection and error identification
refactor - Code refactoring suggestions
review - Comprehensive code review

Security & Performance

security - Security vulnerability analysis
optimize - Performance optimization
scale - Scalability analysis
maintain - Maintainability improvements

Development Process

test - Testing strategy and test cases
document - Documentation improvements
deps-tree - Mermaid dependency trees (external/internal/runtime)
deploy - Deployment and operations

Architecture & Design

patterns - Design pattern applications
architecture - Architecture analysis
api-design - API design evaluation

Templates are available in both English and Japanese, automatically selected based on your system locale or --lang flag.

Custom Prompts

You can also provide your own custom prompt text directly for specific analysis needs:

Custom Prompt Examples

# Custom analysis prompt
list-codes --prompt "Review this code for accessibility issues and suggest improvements"

# Domain-specific analysis
list-codes --prompt "Analyze this machine learning code for data preprocessing best practices"

# Multi-language support
list-codes --prompt "このコードのテスト戦略を評価して改善案を提示してください"

# Specific technology focus
list-codes --prompt "Analyze for React performance anti-patterns" --folder ./components

# Save analysis with custom prompt to file
list-codes --prompt "Code review focusing on error handling" --output review.md

⚙️ Configuration File

list-codes supports a .list-codes.yaml configuration file for persisting include/exclude patterns and options. It is auto-loaded from your project root by default.

.list-codes.yaml Example

# Include/exclude patterns
include:
  - "src/**"
  - "pkg/**"
exclude:
  - "**/*.generated.go"

# Options (overridden by CLI flags when explicitly set)
options:
  include-tests: false
  max-file-size: "1m"
  max-depth: 7

CLI flags take priority over config file values. Use --no-config to disable auto-loading, or --config path to specify a custom config file.

Interactive File Selector (`select` subcommand)

The select subcommand opens a TUI (Terminal User Interface) to interactively browse your project tree and select files. The selection is saved as a .list-codes.yaml config file.

TUI Select Usage

# Open interactive file selector (saves to .list-codes.yaml)
list-codes select

# Specify output config path
list-codes select ./my-config.yaml

📄 Example Output

Below is an example of the output when running list-codes --folder ./my-project. The output includes a Source Code Size Check section, project structure, and source code formatted into a single Markdown file.

Click to view example output ▼

Example Output

## Source Code Size Check

**File Statistics**: 0.15 MB collected, max file: 1.0 MB, max total: unlimited



## Project Structure
```text
. (go-src)
├── .claude
│   └── settings.local.json
├── cmd
│   └── listcodes
│       ├── lang_wrapper.go
│       └── main.go
├── cmd_doc.txt
├── coverage.html
├── coverage.out
├── doc.go
├── generate_docs.sh
├── go.mod
├── go.sum
├── godoc
│   ├── cmd.html
│   ├── main.html
│   ├── README.md
│   └── utils.html
├── GODOC.md
├── list-codes
├── main_doc.txt
├── README.md
├── test-prompt.txt
├── utils
│   ├── config.go
│   ├── config_test.go
│   ├── doc.go
│   ├── file.go
│   ├── file_test.go
│   ├── i18n.go
│   ├── i18n_test.go
│   ├── language.go
│   ├── language_test.go
│   ├── log.go
│   ├── log_test.go
│   ├── messages.go
│   ├── process.go
│   ├── process_test.go
│   ├── prompt.go
│   ├── prompt_i18n.go
│   ├── prompt_test.go
│   ├── test_utils.go
│   ├── utils.go
│   └── utils_main_test.go
└── utils_doc.txt
```

### Go

### cmd/listcodes/lang_wrapper.go

```go
package main

import (
	"os"
	"strings"

	"myutilsport/utils"
)

// parseLanguageFlag manually parses the --lang flag before Cobra processes it
func parseLanguageFlag() bool {
	debugMode := false
	// First check if --debug flag is present
	for _, arg := range os.Args {
		if arg == "--debug" {
			debugMode = true
			break
		}
	}
	for i, arg := range os.Args {
		if arg == "--lang" && i+1 < len(os.Args) {
			langValue := os.Args[i+1]
			if err := utils.SetLanguage(langValue, debugMode); err != nil {
				utils.PrintError("Invalid language: " + langValue)
				os.Exit(1)
			}
			// Debug output for verification
			utils.PrintDebug("Language set to: "+langValue, debugMode)
			return true
		}
		if strings.HasPrefix(arg, "--lang=") {
			langValue := strings.TrimPrefix(arg, "--lang=")
			if err := utils.SetLanguage(langValue, debugMode); err != nil {
				utils.PrintError("Invalid language: " + langValue)
				os.Exit(1)
			}
			// Debug output for verification
			utils.PrintDebug("Language set to: "+langValue, debugMode)
			return true
		}
	}
	return false
}
```

... and so on ...

📜 License

This tool is released under the MIT License. For details, please see the LICENSE file in the GitHub repository.