ails-cli-tool 1.0.3

AI-powered directory scanner and project analyzer

AILS - AI-Powered Directory Scanner & Project Analyzer

🌐 Language

English | 中文

---

A powerful command-line tool that intelligently scans directories, analyzes project structures, and leverages AI to provide deep insights about your codebase. Perfect for developers who want to understand complex projects quickly or document their code automatically.

Features

• AI-Powered Analysis - Leverages advanced language models to understand and describe your project structure
• Smart Directory Scanning - Efficiently scans and categorizes files with intelligent .gitignore support
• Vector Search & Embeddings - Advanced semantic search capabilities with SQLite vector database integration
• Comment Extraction & Injection - Extract and manage code comments across multiple programming languages
• Git Operations - AI automated commit message generation, git workflow integration, and smart diff copying:
  • Copy staged/unstaged changes diff to clipboard
  • Copy diff from any commit (with interactive history selection)
  • Copy all changes (staged + unstaged) with one click
• Advanced Prompt Enhancement - Multi-mode prompt optimization with context-aware file selection:
  • Detailed Mode: Generate comprehensive prompts with implementation suggestions
  • Concise Mode: Create minimal prompts letting AI decide implementation details
  • Question Mode: Answer user questions based on project context
  • Concise Question Mode: Get brief, direct answers with minimal explanation
  • Diff Review Mode: Professional code review for git changes with detailed analysis
  • Concise Diff Review: Quick review of git changes focusing on key issues
  • Code Search Mode: Find relevant code snippets based on user queries

Quick Start

Installation

Install AILS directly from PyPI:

uvx ails-cli-tool

Update to latest version

uvx --force-reinstall ails-cli-tool

First Run

1. Start analyzing your projects:

   ails
   

That's it! AILS will guide you through the rest.

Detailed Installation

PyPI (Recommended)

For stable releases:

uvx ails-cli-tool

System Requirements

• Python 3.8 or higher
• uvx (included with uv)
• Internet connection for AI API calls

Configuration

Initial Setup

Run the configuration wizard to set up your AI API credentials:

ails-config

The wizard will guide you through:

1. Choosing between recommended configuration or manual setup
2. Entering your API credentials
3. Testing the connection
4. Saving the configuration securely

Configuration Options

AILS requires three main settings:

Setting	Description	Example
AI_API_KEY	Your API key for the AI service	sk-xxxxxxxxxxxxxxxx
AI_API_URL	Base URL for the API endpoint	https://api.openai.com/v1
AI_MODEL	Model name to use	gpt-4, gpt-3.5-turbo

Recommended Configuration

AILS offers a one-click recommended configuration that:

• Uses pre-configured, tested API settings
• Automatically validates the connection
• Gets you up and running in seconds

Simply select "Yes" when prompted during ails-config.

Manual Configuration

For custom API providers or specific requirements:

1. Run ails-config
2. Choose manual configuration
3. Enter your specific:
   • API Key
   • API URL (must end in /v1)
   • Model name

Configuration Storage

Configurations are stored securely in:

• Windows: %APPDATA%\AILS\config
• macOS/Linux: ~/.config/ails/config

This ensures your credentials are:

• Separated from project files
• Accessible across all projects
• Easy to update or remove

Usage

Basic Usage

Scan and analyze your current directory:

ails

Language Settings

Switch interface language using environment variables:

English (default):

export AILS_LANG=en
ails

Chinese:

export AILS_LANG=zh
ails

Windows users:

$env:AILS_LANG="zh"
ails

Error Recovery

If AILS encounters an authentication error (401), it will:

1. Detect the issue automatically
2. Ask if you want to use recommended configuration
3. Retry immediately after successful configuration

No need to restart the program!

Advanced Features

Vector Search Integration

AILS includes semantic search capabilities using sqlite-vec:

• Find related code segments
• Discover similar functionality
• Navigate large codebases efficiently

Smart File Filtering

Automatically respects:

• .gitignore patterns
• .kilocodeignore custom patterns
• Standard exclusion rules for common build artifacts

Enhanced Prompts

AILS intelligently enhances prompts to:

• Add relevant context
• Include file metadata
• Optimize token usage

Troubleshooting

Invalid Token Error (401)

Symptom: Error code: 401 - invalid token

Solution:

1. Select "Yes" when prompted to use recommended configuration
2. Or run ails-config manually
3. Verify your API key is correct and active

Connection Timeout

Symptom: API request timeout

Solution:

• Check your internet connection
• Verify the API URL is accessible
• Try using a different network or VPN if blocked

Configuration Not Loading

Symptom: Program keeps asking for configuration

Solution:

# Verify configuration file exists
# Windows:
type %APPDATA%\AILS\config

# macOS/Linux:
cat ~/.config/ails/config

# Re-run configuration wizard
ails-config

Import Errors

Symptom: ModuleNotFoundError

Solution:

# Reinstall with all dependencies
uvx --force-reinstall ails-cli-tool

Dependencies

AILS requires the following packages (automatically installed):

• openai>=1.0.0 - AI API client
• python-dotenv>=1.0.0 - Environment configuration
• requests>=2.25.0 - HTTP requests
• sqlite-vec>=0.1.0 - Vector search
• pathspec>=0.11.0 - Pattern matching
• pyperclip>=1.8.0 - Clipboard operations

Acknowledgments

• Built with ❤️ by the AILS team
• Powered by OpenAI and compatible AI services
• Thanks to all contributors and users

Links

• PyPI: ails-cli-tool

---

Made with ❤️ for developers who want to understand their code better.