## 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!
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!