## What It Does

The tool generates compressed "shorthand" representations of codebases: - 40k LOC → 8k lines (78% compression) - Detects duplicate patterns automatically - Generates layered documentation (overview → modules → files) - Supports Tree of Thoughts (ToT) and Swarm reasoning for complex decisions

## Key Features

*Core:* - AST-based parsing (Python, extensible to other languages) - Pattern detection with similarity clustering - Duplication analysis with refactoring recommendations - Parallel indexing for 1M+ LOC codebases

*AI Integration:* - Multi-model support (Ollama, OpenRouter, Claude) - ToT templates for architecture decisions - Swarm personas for code review (Skeptic, Architect, QA, etc.) - Automated reasoning for complex operations

*CLI Commands:* ```bash ai-shorthand generate /path/to/code --output ./analysis/ ai-shorthand debug /path/to/code --output bugs.md ai-shorthand reasoning tot "Feature Name" --output feature_tot.md ai-shorthand reasoning swarm "Feature Name" --output feature_swarm.md ```

## Validation Study

I ran a 5-phase validation study implementing 5 features in a real codebase:

| Method | Time | Quality | Cognitive Load | |--------|------|---------|----------------| | Manual | 15 min | 8.0/10 | 5/10 | | AI | 15 min | 9.0/10 | 3/10 | | AI+ToT | 20 min | 9.0/10 | 4/10 | | AI+ToT+Swarm | 25 min | 9.5/10 | 4/10 |

*Results:* - +12.5% code quality with AI - -40% cognitive load - 0 bugs across 731 LOC - 3x ROI (time saved vs invested)

Full report: `validation/FINAL_VALIDATION_REPORT.md`

## Technical Details

*Architecture:* - 7 core modules (file discovery, AST parser, pattern scanner, etc.) - 31 unit tests (100% pass) - Parallel processing with ProcessPoolExecutor - LRU caching for pattern similarity (1024 entries) - Security hardening (path validation, symlink protection)

*Performance:* - 118 files (40k LOC) in 0.61s - 857 files/second throughput - 3.6x faster than sequential processing

## Example Usage

```bash # Install pip install ai-shorthand-tool

# Generate shorthand for a codebase ai-shorthand generate ./my-project --output ./analysis/

# Get AI intelligence report ai-shorthand intelligence ./my-project --provider ollama

# Debug analysis with refactoring plan ai-shorthand debug ./my-project --output refactor.md

# Generate ToT template for complex feature ai-shorthand reasoning tot "Add Authentication" \ --complexity medium --output auth_tot.md ```

## Why I Built This

I was tired of: 1. AI tools that add bloat instead of improving code quality 2. Code analysis tools that don't integrate with AI reasoning 3. No validation studies for AI development tools

So I built one with actual metrics and validation.

## What's Different

*Not just another AI wrapper:* - No feature bloat (removed 70 lines of my own AI slop during development) - Actual code quality improvements (split 541-line main() into modules) - Validation study with real data (not marketing claims) - Open source and reproducible

*Bridges hardening + AI:* - Integrated with super_editor_complete.py (1,721 LOC hardened tool) - Added ToT/Swarm hooks for high-risk operations - Opt-in AI (doesn't force AI on simple operations)

## Tech Stack

- Python 3.8+ - Click (CLI), Rich (output) - AST (parsing), difflib (similarity) - Optional: Ollama/OpenRouter/Claude for AI features

## Roadmap

*v2.2 (Q2 2026):* - Web UI for visualization - VS Code extension - Multi-language support (Go, JS/TS)

*v3.0 (Q4 2026):* - Autonomous refactoring agent - CI/CD integration - Cloud deployment

## Feedback Wanted

1. Is the validation study convincing? 2. What features would you actually use? 3. Any showstoppers for adoption?

Happy to answer questions!