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

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.

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

pip install devco

devco init

devco principles add --text "Follow Test-Driven Development"
devco principles add --text "Keep functions under 20 lines"
devco principles add --text "Use specific function names and file paths in documentation"

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."

devco section add testing \
  --summary "TDD with pytest and comprehensive isolation" \
  --detail "Tests in tests/ directory. Run: pytest -v. Key patterns: TestCase classes with temp_dir fixtures, @patch decorators for mocking, isolated DevDocStorage(tmpdir) per test. Example: test_add_principle() in tests/test_principles.py:33."

devco embed

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

When working with AI assistants on any project, establish this pattern:

1. Initialize devco immediately: devco init
2. Document as you go: After each feature/change, update relevant sections
3. Query before exploring: devco query "topic" before searching files
4. Capture user feedback: Document requirements and future work

✅ Start every session with:

devco summary    # Understand the project
devco principles # Know the coding standards

✅ Before implementing features:

devco query "authentication"      # Find existing patterns
devco query "database models"     # Understand data layer
devco query "testing framework"   # Follow test patterns

✅ After implementing features:

devco section add feature_name \
  --summary "Brief description" \
  --detail "Implementation details with function names, file paths, and usage examples"

Instead of:

AI: Let me explore your codebase to understand how you handle user authentication...
[reads 10+ files, makes assumptions]

Use:

AI: devco query "authentication"
AI: Perfect! I can see you use JWT tokens with UserService.authenticate() 
    in src/auth/service.py:45, and tests follow the pattern in 
    tests/test_auth.py:test_login_success().

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

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

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

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

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

devco automatically commits all documentation changes to git:

devco principles add --text "New principle"
# → Creates git commit: "devco: update principles"

devco summary replace --text "Updated project description"  
# → Creates git commit: "devco: update summary"

devco section add feature --summary "..." --detail "..."
# → Creates git commit: "devco: update summary"

Features:

• Automatic commits: Every devco change creates a descriptive git commit
• Staging preservation: Your staged files remain untouched
• Safe operation: Only commits devco files, ignores non-git projects
• Clean history: Each devco action gets its own commit with clear messages

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.

• 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

• 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
• Git Integration: Automatic commits for all devco changes with staging preservation

.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)

• Python 3.8+
• llm package with Gemini plugin
• Google API key for 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

Configure in .devco/config.json:

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

✅ 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

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"

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

MIT License - see LICENSE file for details.

• Documentation
• Issues
• Changelog