✨ Features

• 🧠 Automated Gap Analysis: Automatically compares new specs against your existing codebase and categorizes requirements:
  • ✅ Reuse: Code already exists.
  • ⚠️ Extend: Code exists but needs modification.
  • ❌ Conflict: Requirement contradicts existing logic.
  • 🔨 Net New: Entirely new implementation required.
• 🔒 Local & Private: Fully supports running locally via Ollama and local ChromaDB embeddings. Your code never has to leave your machine.
• 🔌 Model Context Protocol (MCP): Leverages official MCP servers to safely read your filesystem and fetch GitHub issues, alongside custom Python MCP servers for AST parsing and semantic RAG.
• ⏱️ Effort Estimation & Planning: Uses heuristic baselines and LLM reasoning to estimate implementation hours and suggest an optimal implementation order.
• 🎨 Beautiful Output: Renders beautiful Rich terminal UI interfaces and persists detailed Markdown reports for your team.

🛠️ Architecture

DevAgent uses a multi-agent LangGraph pipeline orchestrated via MCP:

graph TD
    Spec[Spec Source: GitHub, Markdown, Text] --> Parser[SpecParser Agent]
    Parser --> Context[Web Context via Brave/SearchX]
    Parser --> Reqs[Extracted Atomic Requirements]
    Reqs --> Inventory[CodeInventory Agent]
    Inventory <--> Chroma[(ChromaDB Vector Store)]
    Inventory --> Gap[Requirement Classifications]
    Gap --> Reporter[GapReport Agent]
    Reporter --> UI[Rich Terminal UI & Markdown Report]
    
    style Parser fill:#f9f,stroke:#333,stroke-width:2px
    style Inventory fill:#bbf,stroke:#333,stroke-width:2px
    style Reporter fill:#dfd,stroke:#333,stroke-width:2px

🚀 Installation

DevAgent is a Python CLI tool. The recommended way to install it is via pipx to keep its dependencies isolated:

pipx install devagent

(Alternatively, you can install it globally or in a virtual environment using pip install devagent).

⚠️ System Requirements

Because DevAgent utilizes official Model Context Protocol (MCP) servers under the hood, you must have Node.js installed on your machine.

• Download and install Node.js (Ensure npx is available in your PATH).

⚙️ Configuration & Setup

Before analyzing your first project, initialize the global configuration:

devagent init

This interactive prompt will help you set up:

• LLM Provider: Choose between Ollama (local), Groq, Anthropic, OpenAI, or Gemini.
• GitHub Token: (Optional) Required if you want DevAgent to fetch specs directly from GitHub Issues.
• Search Provider: (Optional) Brave or SearchX for gathering web context on implementation patterns.

You can always view or modify your config later using devagent config --show or devagent config --set key=value.

💻 Usage

1. Index your Codebase

Navigate to your project directory and build the semantic search index. This uses local AST parsing (for Python) and text chunking to embed your codebase into a local ChromaDB instance.

cd /path/to/your/project
devagent index

Note: DevAgent respects your .gitignore files automatically. Re-running this command performs an incremental index (only updating changed files).

2. Analyze a Specification

Run a gap analysis against your codebase using a GitHub Issue, a local Markdown file, or inline text:

# Analyze a GitHub Issue (requires GitHub Token in config)
devagent analyze --issue 142 --repo owner/my-repo

# Analyze a local spec file
devagent analyze --spec ./docs/new_feature.md

# Analyze inline text
devagent analyze --text "Add a new user authentication endpoint supporting OAuth2."

By default, this outputs a beautiful Rich terminal report and saves a .md markdown report in your local app data directory.

3. Manage Reports

View previously generated reports for the current project:

# List all saved reports
devagent reports

# View a specific report in the terminal
devagent reports --show issue-142

4. Semantic Search

Need to quickly find where something is implemented? Use the standalone semantic search:

devagent search "user authentication logic"

🩺 Troubleshooting

If you run into issues with dependencies or services, run the built-in doctor command to check the health of your environment:

devagent doctor

🤝 Contributing

Contributions are welcome! Please check out the issues page or submit a pull request.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.