3 ms·
## What It Does The tool generates compressed "shorthand" representations of codebases: - 40k LOC → 8k lines (78% compression) - Detects duplicate patterns aut
by larryste 7mo ago
## 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!