🧵 CodeWeaver

Weave your codebase into AI-ready documentation

An intelligent source code aggregation tool with AI-powered file selection, dependency analysis, and flexible compression options.

✨ Key Features

• 🤖 AI-Powered File Selection - Find files using natural language queries
• 📊 Dependency Analysis - Visualize imports, detect circular dependencies
• 🗜️ Smart Compression - 4 modes: None, Semantic (67%), Lossless (75%), Hybrid
• 🔍 Advanced Search - Full-text search, bulk selection, extension filters
• 📄 Markdown Export - Generate AI-ready documentation with syntax highlighting

🚀 Quick Start

# Clone and install
git clone https://github.com/yourusername/codeweaver.git
cd codeweaver
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure (create .env file)
OPENROUTER_API_KEY=your_openrouter_key_here
OPENROUTER_MODEL=google/gemma-3-27b-it:free

# Run
python app.py
# Open http://localhost:5000

📖 Usage

1. Analyze Directory

Enter path → Click "Analyze" → View file tree

2. Select Files

Manual: Click checkboxes in tree
Bulk: Enter filenames (one per line)
AI: Natural language query

Example: "Find all files related to user authentication"

3. Generate Documentation

Choose compression mode → Click "Generate" → Download

🗜️ Compression Modes

Mode	Size	Restoration	Best For
None	100%	✅ Perfect	Small projects
Semantic	33%	❌ Structure only	AI analysis
Lossless	25%	✅ Perfect	Archival
Hybrid	33%	✅ With reference	Large projects

🏗️ Tech Stack

Backend: Flask, OpenRouter API, NetworkX, Google Gemini compatibility for non-selection flows Frontend: Vanilla JS, D3.js, Mermaid

📋 Requirements

• Python 3.8+
• OpenRouter API key (Get one here)

🔧 Configuration

Create .env file:

OPENROUTER_API_KEY=your_openrouter_key
OPENROUTER_MODEL=google/gemma-3-27b-it:free  # or another OpenRouter-supported model
OPENROUTER_API_URL=https://openrouter.ai/api/v1/chat/completions
OPENROUTER_REQUEST_TIMEOUT=120
OPENROUTER_TIMEOUT=120                # legacy alias if REQUEST_TIMEOUT is omitted
OPENROUTER_MAX_RETRIES=3              # retry attempts for 429/5xx
OPENROUTER_INITIAL_RETRY_DELAY=1.0
OPENROUTER_MAX_RETRY_DELAY=30.0
OPENROUTER_RETRY_JITTER_SECONDS=0.4
OPENROUTER_TEMPERATURE=0.7
OPENROUTER_TOP_P=0.95
OPENROUTER_MAX_TOKENS=8192
AI_SELECT_MAX_FILES_FOR_PROMPT=2000  # optional: keep AI payload small for large projects

AI_SELECT_MAX_FILES_FOR_PROMPT controls how many file entries are sent to OpenRouter during AI selection. When the project has many files, the endpoint now sends a compact filename manifest first and truncates to this limit to reduce payload and avoid frequent rate limits.

OpenRouter 429 guidance

• OPENROUTER_MAX_RETRIES: increase this only if each retry is backed by retry_after guidance from OpenRouter.
• OPENROUTER_INITIAL_RETRY_DELAY, OPENROUTER_MAX_RETRY_DELAY, OPENROUTER_RETRY_JITTER_SECONDS: tune these to spread requests when you get bursts of 429s.
• AI_SELECT_MAX_FILES_FOR_PROMPT: reducing this lowers prompt size and improves consistency on free-tier keys.
• OPENROUTER_TIMEOUT / OPENROUTER_REQUEST_TIMEOUT: keep timeouts moderate for short prompts and large projects.

🐛 Troubleshooting

AI Selection Error?

• Check API key is valid
• Verify OPENROUTER_API_KEY is set and has credits
• Ensure the selected model is available in your OpenRouter account
• On repeated 429, wait at least the suggested Retry-After period and retry. If issues persist, reduce AI_SELECT_MAX_FILES_FOR_PROMPT and increase backoff values.

Encoding Issues?

• CodeWeaver auto-detects encoding via chardet

Large Project Slow?

• Use extension filters
• Enable hybrid compression

🤝 Contributing

# Fork → Create branch → Make changes → Submit PR
git checkout -b feature/AmazingFeature

See CONTRIBUTING.md for details.

📝 License

MIT License - see LICENSE

🙏 Credits

Built with Flask, OpenRouter AI routing, D3.js, and ❤️!

---

⭐ Star this repo if you find it useful!

📧 Issues: GitHub Issues