aicontext - AI Context Generator¶

aicontext [options] [directory]
```bash

### Options

- `-o FILE`: Output to file (default: stdout)
- `-f FORMAT`: Output format (markdown, json, xml)
- `-d DEPTH`: Analysis depth (1-5, default: 3)
- `-i PATTERN`: Include pattern (glob)
- `-x PATTERN`: Exclude pattern (glob)
- `-l LANG`: Focus on specific language
- `-t TYPE`: Context type (full, summary, code-only)
- `-v`: Verbose output
- `-h`: Show help

## Examples

### Basic Usage

```bash
# Generate context for current directory
aicontext

# Analyze specific project
aicontext ~/projects/my-app/

# Save to file
aicontext -o project-context.md
```bash

### Filtered Analysis

```bash
# Focus on Python files
aicontext -l python

# Include only source files
aicontext -i "*.py" -i "*.js" -x "test_*" -x "*_test.py"

# Deep analysis
aicontext -d 5 ~/large-project/
```bash

### Output Formats (Context)

```bash
# Markdown (default, human-readable)
aicontext -f markdown -o README.md

# JSON (machine-readable)
aicontext -f json -o context.json

# XML (structured data)
aicontext -f xml -o context.xml
```bash

### Context Types

```bash
# Full context (default)
aicontext -t full

# Summary only
aicontext -t summary

# Code snippets only
aicontext -t code-only
```bash

## How It Works

### Analysis Pipeline

1. **Structure Discovery**: Maps directory structure
2. **File Classification**: Identifies file types and languages
3. **Dependency Analysis**: Finds imports, requires, includes
4. **Code Analysis**: Extracts key functions, classes, patterns
5. **Documentation Mining**: Gathers READMEs, comments, docs
6. **Context Synthesis**: Creates coherent project overview

### Intelligence Features

- **Language Detection**: Automatic programming language identification
- **Framework Recognition**: Detects frameworks (React, Django, etc.)
- **Architecture Patterns**: Identifies MVC, microservices, etc.
- **Dependency Mapping**: Builds dependency graphs
- **Code Quality Assessment**: Basic complexity and structure analysis

## Configuration

### Configuration File

```toml
# ~/.config/aicontext/config.toml
[analysis]
max_depth = 3
max_files = 1000
timeout = 30

[output]
format = "markdown"
include_code_samples = true
max_code_lines = 50

[filters]
include_patterns = ["*.py", "*.js", "*.ts", "*.go"]
exclude_patterns = ["*.pyc", "__pycache__", "node_modules"]

[languages]
python = { frameworks = ["django", "flask", "fastapi"] }
javascript = { frameworks = ["react", "vue", "angular"] }
```bash

### Environment Variables

```bash
# Analysis settings
export AICTXT_MAX_DEPTH=4
export AICTXT_TIMEOUT=60

# Output preferences
export AICTXT_FORMAT=json
export AICTXT_VERBOSE=1

# Custom patterns
export AICTXT_INCLUDE="*.rs,*.go"
export AICTXT_EXCLUDE="target/,build/"
```bash

## Dependencies

### Required

- **file**: File type detection
- **find**: Directory traversal
- **grep**: Pattern matching
- **sed/awk**: Text processing

### Optional

- **tree**: Enhanced directory display
- **ctags**: Code structure analysis
- **cloc**: Code statistics
- **tokei**: Language detection

## Troubleshooting

### Analysis Timeout

**Symptom:** "Analysis timeout" error

**Cause:** Large project or slow system

**Fix:**

```bash
# Increase timeout
export AICTXT_TIMEOUT=120

# Reduce depth
aicontext -d 2

# Exclude large directories
aicontext -x "node_modules/" -x "build/"
```bash

### Memory Issues

**Symptom:** Out of memory error

**Cause:** Too many files or large codebase

**Fix:**

```bash
# Limit file count
export AICTXT_MAX_FILES=500

# Use summary mode
aicontext -t summary

# Filter files
aicontext -i "*.py" -x "test_*"
```bash

### Incorrect Language Detection

**Symptom:** Wrong language identified

**Cause:** Unusual file extensions or mixed languages

**Fix:**

```bash
# Specify language
aicontext -l python

# Check file types
file unknown-file.ext

# Update patterns
# Edit ~/.config/aicontext/config.toml
```bash

### Missing Dependencies

**Symptom:** "Command not found" errors

**Cause:** Required tools not installed

**Fix:**

```bash
# Install required tools
sudo apt install file findutils grep sed gawk

# Install optional tools
sudo apt install tree universal-ctags cloc tokei
```bash

## Performance

### Benchmarks

| Project Size        | Files | Time | Memory |
| ------------------- | ----- | ---- | ------ |
| Small (<100 files)  | 50    | 2s   | 20MB   |
| Medium (100-1000)   | 500   | 15s  | 100MB  |
| Large (1000-10000)  | 5000  | 120s | 500MB  |
| Very Large (>10000) | 20000 | 600s | 2GB    |

### Optimization Tips

- **Filter early**: Use include/exclude patterns
- **Limit depth**: Start with shallow analysis
- **Use summary mode**: For large projects
- **Cache results**: Reuse context files
- **Parallel processing**: For multi-core systems

## Integration

### With AI Assistants

```bash
# Generate context before asking AI
aicontext -o context.md
# Then paste context.md into AI chat

# Quick summary for AI
aicontext -t summary | xclip -selection clipboard
```bash

### With Development Workflow

```bash
#!/bin/bash
# Pre-commit hook
aicontext -t summary > .aicontext
git add .aicontext

# CI/CD integration
aicontext -f json -o context.json
# Upload to AI service
```bash

### With Documentation

```bash
# Generate project overview
aicontext -f markdown -o PROJECT.md

# Update README with context
aicontext -t summary >> README.md
```bash

### With Code Review

```bash
# Context for code review
aicontext -l python -d 2 -o review-context.md
# Share with reviewers

# Focus on specific module
aicontext -i "mymodule/**" -o module-context.md
```bash

## Output Formats

### Markdown Format

```markdown
# Project Context: my-project

## Overview

- Language: Python
- Framework: Django
- Files: 245
- Lines: 15432

## Structure

my-project/
├── src/
│ ├── main.py
│ └── utils.py
├── tests/
└── docs/
```bash

## Key Components

- `main.py`: Application entry point
- `utils.py`: Utility functions

## Dependencies (Project)

- django==3.2.0
- requests==2.25.0

## Code Examples

```python
# main.py
def main():
  print("Hello World")
```bash

### JSON Format

```json
{
  "project": {
    "name": "my-project",
    "language": "python",
    "framework": "django",
    "metrics": {
      "files": 245,
      "lines": 15432,
      "complexity": "medium"
    }
  },
  "structure": {
    "directories": ["src", "tests", "docs"],
    "key_files": ["main.py", "utils.py"]
  },
  "dependencies": [
    {"name": "django", "version": "3.2.0"},
    {"name": "requests", "version": "2.25.0"}
  ],
  "code_samples": [
    {
      "file": "main.py",
      "language": "python",
      "content": "def main():\n    print(\"Hello World\")"
    }
  ]
}
```bash

## Technical Details

### Language Support

- **Python**: Django, Flask, FastAPI detection
- **JavaScript**: React, Vue, Angular, Node.js
- **Java**: Spring, Maven, Gradle
- **Go**: Standard library, popular frameworks
- **Rust**: Cargo, common crates
- **C/C++**: Make, CMake, common libraries
- **And more**: 50+ languages supported

### Analysis Algorithms

- **Dependency Graph**: Import/require analysis
- **Code Complexity**: Cyclomatic complexity estimation
- **Architecture Detection**: Pattern recognition
- **Documentation Extraction**: README and comment mining
- **Quality Metrics**: Basic code quality scoring

### Caching System

- **File Hashes**: Detects file changes
- **Incremental Updates**: Only re-analyzes changed files
- **Result Caching**: Stores analysis results
- **Cache Invalidation**: Automatic cleanup

### Security Considerations

- **No Code Execution**: Static analysis only
- **Safe File Access**: Read-only operations
- **Path Sanitization**: Prevents directory traversal
- **Size Limits**: Prevents resource exhaustion

## See Also

- **[docgen](docgen.md)** - Documentation generator
- **[scaffold](scaffold.md)** - Project scaffolding
- **[AI Integration](../../README.md#ai-assistants)** - AI assistant integration guide