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 to omit or target specific files and directories. Smart dotfile exclusion with override capabilities.

📊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.

🎯Structured Output

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

🛠️ 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     Folder path to include (repeatable)
--exclude, -e     Folder path to exclude (repeatable)
--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)

# 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

🎯 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
migrate - Technology stack migration
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

📄 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.