devco 0.1.5

A CLI tool that helps AI assistants understand projects through persistent documentation and RAG search

devco

A CLI tool that helps AI assistants understand projects by managing persistent documentation, principles, and context through embeddings and RAG querying.

🎯 Problem

AI assistants lose context when working on projects across sessions. They waste time re-exploring codebases, re-learning project structure, and rediscovering development practices with every new conversation.

✨ Solution

devco creates persistent, searchable project knowledge that survives context resets:

• Development Principles - Your team's coding standards and practices
• Project Summary - High-level project description and purpose
• Technical Sections - Detailed implementation guides with function names, file paths, and examples
• RAG Search - Semantic search across all documentation using vector embeddings

🚀 Quick Start

Installation

pip install devco

Initialize in your project

devco init

Add your development principles

devco principles add --text "Follow Test-Driven Development"
devco principles add --text "Keep functions under 20 lines"

Document your project

devco summary replace --text "FastAPI web service for user authentication with PostgreSQL backend"

devco section add architecture \
  --summary "Clean architecture with dependency injection" \
  --detail "Entry point: main.py:create_app() line 15. Uses FastAPI with dependency injection via Depends(). Database models in models/ directory. Business logic in services/ with UserService.create_user() method."

Generate embeddings for semantic search

devco embed

Query your documentation

devco query "how does authentication work"
devco query "testing approach"
devco query "database schema"

📚 Full Documentation

View all content

devco summary          # Show project summary and all sections
devco principles       # List development principles
devco section show testing  # Show specific section

Manage principles

devco principles                              # List all
devco principles add --text "New principle"   # Add with flag
devco principles add                          # Add interactively  
devco principles rm 2                         # Remove by number
devco principles clear                        # Remove all

Manage summary

devco summary                                # Show current
devco summary replace --text "New summary"   # Replace with flag
devco summary replace                        # Replace interactively

Manage sections

devco section show architecture              # Show specific section
devco section add testing \
  --summary "TDD with pytest" \
  --detail "Tests in tests/ directory. Run: pytest -v"
devco section replace api --summary "..." --detail "..."
devco section rm outdated-section

Search and embeddings

devco embed                    # Generate embeddings for all content
devco query "database setup"   # Semantic search
devco query "testing framework" 

🏗️ Why This Works

For AI Assistants

Instead of this inefficient pattern:

AI: Let me search through your files to understand the project...
AI: *uses grep, find, reads multiple files*
AI: *tries to infer patterns and practices*
AI: OK, I think I understand how this works...

You get this efficient pattern:

AI: devco query "testing approach"
AI: Perfect! I can see you use pytest with TDD methodology, 
    tests are in tests/ directory, and I should follow the 
    pattern in tests/test_user.py:test_create_user() line 25.

For Development Teams

• Onboarding: New developers get instant project context
• Consistency: Shared principles ensure consistent code
• Documentation: Implementation details with specific examples
• Knowledge Retention: Project knowledge survives team changes

🔧 Technical Details

Architecture

• CLI Framework: argparse with subcommands
• Storage: JSON files + SQLite for vector embeddings
• Embeddings: Gemini via llm package for consistent results
• Search: Cosine similarity with chunked content and overlap

File Structure

.devco/
├── config.json      # Settings and embedding model
├── principles.json  # Development principles  
├── summary.json     # Project summary and sections
├── devco.db       # SQLite database with embeddings
└── .env           # API keys (git-ignored)

Requirements

• Python 3.8+
• llm package with Gemini plugin
• Google API key for embeddings

⚙️ Configuration

Set up embeddings

1. Install the llm package: pip install llm llm-gemini
2. Add your Google API key to .devco/.env:

   GOOGLE_API_KEY=your_key_here
   

3. Generate embeddings: devco embed

Embedding Models

Configure in .devco/config.json:

{
  "embedding_model": "gemini-embedding-exp-03-07-2048",
  "chunk_size": 500,
  "chunk_overlap": 50
}

📖 Best Practices

Documentation Content

✅ Include specific details:

• Function names: UserService.authenticate()
• File paths: src/auth/service.py:45
• Command examples: pytest tests/test_auth.py -v
• Code snippets and patterns

✅ Write for AI assistants:

• Assume no prior context
• Include implementation details
• Specify exact locations and examples

❌ Avoid vague descriptions:

• "We use good practices" → Specify what practices
• "Tests are important" → Specify testing framework and patterns
• "Code is modular" → Specify module structure and key classes

Principles

Good principles are specific and actionable:

• ✅ "Use pytest fixtures for database setup in tests/conftest.py"
• ✅ "API endpoints follow REST patterns with serializers in api/serializers.py"
• ❌ "Write good code"
• ❌ "Be consistent"

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Follow TDD: write tests first
4. Ensure all tests pass: pytest -v
5. Update documentation with specific implementation details
6. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Documentation
• Issues
• Changelog