✨ Context Buddy

Context Buddy is an AI-powered agent designed to understand your codebase deeply. It goes beyond simple text search by extracting architectural insights, tracking dependencies, and clustering components to answer high-level system questions.

🚀 Key Features

• 🧠 Cognitive Indexing: Semantic vector search powered by ChromaDB and Gemnini.
• 🏛️ Architecture Extraction: Automatically reverse-engineers system design (File Roles, Dependencies, Call Graphs).
• 💼 Business Analyst Suite: Translate code into business value:
  • Explain: Deciphers complex logic into plain English rules.
  • Trace: Maps the impact surface of a variable or feature change.
  • Audit: Discovers unhandled edge cases and risks.
  • Spec: Reverse-engineers a functional specification.
  • Flow: Generates Mermaid sequence diagrams for any process.
• 🎓 Onboarding: Generates a "Day 1" guide for new developers.
• 🔌 Plug-and-Play: Runs fully containerized with Docker.

📦 Installation & Setup

Option 1: Docker (Recommended)

The easiest way to run Context Buddy is via Docker Compose, which handles the database and dependencies for you.

1. Clone the repository:

   git clone https://github.com/your-username/context-buddy.git
   cd context-buddy

2. Configure Environment: Create a .env file in the root directory:

   GENAI_KEY=your_gemini_api_key_here
   LLM_PROVIDER=gemini
   CHROMA_MODE=http
   CHROMA_HOST=chroma

3. Run with Docker: To access the CLI inside the container:

   docker-compose run --rm buddy --help

Option 2: Local Python

If you prefer running locally without Docker:

1. Install Dependencies:

   pip install -r requirements.txt

2. Run:

   python buddy-cli.py --help

🛠️ Usage Guide

1. Index Your Codebase

Before asking questions, you must index the target repository.

# Docker
docker-compose run --rm buddy index-repo /path/to/target/repo

# Local
python buddy-cli.py index-repo .

This generates architecture artifacts in data/architecture and vector embeddings in data/index.

2. Business Analyst Commands

Context Buddy truly shines when analyzing business logic.

Command	Description	Example
explain	Explains "Business Rules" for a feature.	buddy explain "Reward Calculation"
trace	Traces dependencies and impact of a change.	buddy trace "User.is_active"
audit	Finds edge cases and risks in a module.	buddy audit "PaymentService"
spec	Reverse-engineers a Functional Spec.	buddy spec "Checkout Flow"
flow	Generates a Mermaid Sequence Diagram.	buddy flow "Data Ingestion"
describe	Generates a Data Dictionary table.	buddy describe
verify	Checks code against a requirement.	buddy verify "Passwords must be hashed"
journey	Maps a user's step-by-step journey.	buddy journey "Reset Password"
onboard	Generates a developer onboarding guide.	buddy onboard

3. Architecture Commands

• arch: View high-level architecture summary.
• deps: Visualize dependency tree.
• diagram: Generate a visual Class Diagram.

4. General Q&A

Ask free-form questions about the codebase.

docker-compose run --rm buddy ask "How does the authentication middleware handle timeouts?"

🏗️ Technical Architecture

• Ingestion: Tree-sitter parsing + Semantic Chunking + Vector Embedding.
• Storage: ChromaDB (Vector Store) + JSON Artifacts (Graph Data).
• Analysis: Hybrid Retrieval (Keyword + Semantic) + LLM Synthesis.
• Visuals: Mermaid.js / Kroki for diagram generation.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.