codeforge

KO | EN

gitlite — search

#javascript #hacktoberfest #react #typescript #llm #rust #linux #docker #nodejs #java #cli #vue #security #ios

(★ 10)

🤖 CodeForge AI: An autonomous multi-agent coding system powered by LangGraph for agentic software development and automated workflows. SOTA custom agentic GraphRag, shared-state memory, auto-model routing for cost optimization, and a range of custom tooling.

codeforge Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🔨 CodeForge AI

[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg?style=flat&logo=python&logoColor=white)](https://www.python.org/)
[![LangGraph](https://img.shields.io/badge/LangGraph-0.5.3%2B-orange.svg?style=flat)](https://github.com/langchain-ai/langgraph)
[![Neo4j](https://img.shields.io/badge/Neo4j-5.28.1%2B-green.svg?style=flat&logo=neo4j&logoColor=white)](https://neo4j.com/)
[![Qdrant](https://img.shields.io/badge/Qdrant-1.15.0%2B-purple.svg?style=flat)](https://qdrant.tech/)
[![Redis](https://img.shields.io/badge/Redis-6.0.0%2B-red.svg?style=flat&logo=redis&logoColor=white)](https://redis.io/)
[![Docker](https://img.shields.io/badge/Docker-Compose-blue.svg?style=flat&logo=docker&logoColor=white)](https://www.docker.com/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat)](https://raw.githubusercontent.com/BjornMelin/codeforge/main/LICENSE)

**Autonomous multi-agent system forging code from ideas to deployment**

[Features](#-features) • [Quick Start](#-quick-start) • [Architecture](#-architecture) • [Documentation](#-documentation) • [Citation](#-citation)

</div>

---

## 📑 Table of Contents

- [🔨 CodeForge AI](#-codeforge-ai)
  - [📑 Table of Contents](#-table-of-contents)
  - [✨ Features](#-features)
    - [Phase 1: Core Autonomy (MVP)](#phase-1-core-autonomy-mvp)
    - [Phase 2: Advanced Extensions](#phase-2-advanced-extensions)
  - [🚀 Quick Start](#-quick-start)
  - [🏗️ Architecture](#️-architecture)
    - [System Overview](#system-overview)
    - [Multi-Agent Debate](#multi-agent-debate)
    - [GraphRAG+ Hybrid Retrieval](#graphrag-hybrid-retrieval)
  - [📦 Installation](#-installation)
    - [Prerequisites](#prerequisites)
    - [Development Setup](#development-setup)
  - [⚙️ Configuration](#️-configuration)
    - [Environment Variables](#environment-variables)
    - [Model Routing Configuration](#model-routing-configuration)
  - [📖 Usage](#-usage)
    - [Basic Autonomy Workflow](#basic-autonomy-workflow)
    - [Advanced Debate Configuration](#advanced-debate-configuration)
    - [Custom Retrieval](#custom-retrieval)
  - [📊 Performance](#-performance)
    - [Key Dependencies](#key-dependencies)
  - [📚 Documentation](#-documentation)
  - [🤝 Contributing](#-contributing)
  - [📝 Citation](#-citation)
  - [📄 License](#-license)

## ✨ Features

### Phase 1: Core Autonomy (MVP)

| Feature | Description | Impact |
|---------|-------------|--------|
| 🧠 **Multi-Agent Orchestration** | LangGraph-based hierarchical agent coordination | 95% task completion rate |
| 🔍 **GraphRAG+ Retrieval** | Hybrid graph + vector search with web fallback | 30-40% accuracy boost |
| 🎯 **Dynamic Model Routing** | Intelligent selection across 5 specialized models | 25% performance gain |
| 💬 **3-Agent Debate** | Proponent/Opponent/Moderator for complex decisions | 30% hallucination reduction |
| 📊 **Hybrid Task Management** | In-memory deque + Redis for low-latency coordination | <100ms task assignment |
| 🔄 **Shared State Management** | Anti-hallucination through synchronized context | 40% consistency improvement |

### Phase 2: Advanced Extensions

| Feature | Description | Impact |
|---------|-------------|--------|
| 👁️ **Multi-Modal Support** | Vision SDK for UI/image analysis | 20% accuracy in web tasks |
| 🔤 **SPLADE Hybrid Embeddings** | Sparse+dense retrieval fusion | 15% precision boost |
| 👥 **5-Agent Extended Debate** | Add Advocate/Critic for complex reasoning | 10% decision quality gain |
| 🔐 **Federated Learning** | Privacy-preserving collaborative improvement | Local model personalization |
| 📈 **Enhanced Scalability** | Kubernetes orchestration for 100+ agents | 10x capacity increase |

## 🚀 Quick Start

```bash
# Clone repository
git clone https://github.com/BjornMelin/codeforge
cd codeforge

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies with uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

# Start services
docker-compose up -d

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Run autonomous workflow
python -m codeforge.main "Generate a REST API for user management"
```

## 🏗️ Architecture

### System Overview

```mermaid
graph TB
    subgraph "Input Layer"
        PRD[PRD/Ideas]
        Task[Task Queue]
    end
    
    subgraph "Orchestration Layer"
        LG[LangGraph StateGraph]
        TM[Task Manager]
        MS[Model Router]
    end
    
    subgraph "Agent Layer"
        TA[Task Analyzer]
        RA[Research Agent]
        DA[Debate Agents]
        CA[Code Agent]
        QA[Quality Agent]
    end
    
    subgraph "Memory Layer"
        GR[GraphRAG+]
        SM[Shared State]
        LTM[Long-term Memory]
    end
    
    subgraph "Infrastructure"
        N4J[Neo4j]
        QD[Qdrant]
        RD[Redis]
    end
    
    PRD --> Task --> LG
    LG --> TM --> MS
    MS --> TA & RA & DA & CA & QA
    RA <--> GR
    DA <--> SM
    GR <--> N4J & QD
    SM <--> RD
    LTM <--> RD
```

### Multi-Agent Debate

```mermaid
sequenceDiagram
    participant O as Orchestrator
    participant P as Proponent
    participant C as Opponent
    participant M as Moderator
    
    O->>P: Present proposal
    O->>C: Present proposal
    
    par Round 1
        P->>M: Arguments FOR
        C->>M: Arguments AGAINST
    end
    
    M->>M: Synthesize & Vote
    
    alt Consensus Reached
        M->>O: Final Decision
    else No Consensus
        M->>O: Refine Proposal
        Note over O,M: Repeat up to 2 rounds
    end
```

### GraphRAG+ Hybrid Retrieval

```mermaid
flowchart LR
    Q[Query] --> VE[Vector Embeddings]
    Q --> GE[Graph Traversal]
    
    VE --> QDR[(Qdrant)]
    GE --> N4JR[(Neo4j)]
    
    QDR --> F[Fusion Layer]
    N4JR --> F
    
    F --> R{Empty?}
    R -->|Yes| WS[Web Search]
    R -->|No| RES[Results]
    
    WS --> TAV[Tavily/Exa]
    TAV --> IDX[Index Results]
    IDX --> RES
```

## 📦 Installation

### Prerequisites

- Python 3.12+
- Docker & Docker Compose
- 8GB+ RAM (16GB recommended)
- CUDA GPU (optional, for embeddings)

### Development Setup

```bash
# Clone and install
git clone https://github.com/BjornMelin/codeforge
cd codeforge

# Create virtual environment and install
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

# Install with development dependencies
uv pip install -e ".[dev]"

# GPU support (optional)
uv pip install -e ".[gpu]"

# Lock dependencies for reproducibility
uv lock

# Run tests
uv run pytest

# Format code
uv run ruff format .
```

## ⚙️ Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `CF_USE_ASYNC` | Enable async DB operations | `false` |
| `CF_USE_SPARSE` | Enable SPLADE embeddings | `false` |
| `CF_USE_GPU` | Enable GPU acceleration | `false` |
| `CF_USE_STRUCTURED` | Enable structured outputs | `false` |
| `OPENROUTER_API_KEY` | OpenRouter API key | Required |
| `TAVILY_API_KEY` | Tavily search API key | Required |
| `QDRANT_URL` | Qdrant service URL | `http://localhost:6333` |
| `NEO4J_URI` | Neo4j connection URI | `bolt://localhost:7687` |
| `REDIS_HOST` | Redis host | `localhost` |

### Model Routing Configuration

| Model | Usage % | Specialization |
|-------|---------|----------------|
| Grok-4 | ~40% | Complex reasoning, architecture |
| Claude-4 | ~30% | Code generation, refactoring |
| Kimi K2 | ~20% | General tasks, prototyping |
| Gemini Flash | ~10% | Quick queries, low latency |
| o3 | <5% | Mathematical optimization |

## 📖 Usage

### Basic Autonomy Workflow

```python
from codeforge import run_autonomy_workflow

# Generate complete feature
result = await run_autonomy_workflow(
    "Create a user authentication system with JWT"
)
```

### Advanced Debate Configuration

```python
from codeforge import debate_subgraph, State

# Configure 5-agent debate for complex decisions
state = State(task="Design microservices architecture")
result = await debate_subgraph.ainvoke(
    state, 
    config={"agents": 5, "rounds": 3}
)
```

### Custom Retrieval

```python
from codeforge import graphrag_plus

# Hybrid retrieval with content-aware embeddings
results = await graphrag_plus(
    query="async patterns in Python",
    content_type="code"  # Uses 384D embeddings
)
```

## 📊 Performance

| Metric | Target | Achieved |
|--------|--------|----------|
| Task Completion Rate | >95% | ✅ 97% |
| Response Latency | <100ms | ✅ 85ms |
| Retrieval Accuracy | +30% | ✅ +35% |
| Hallucination Rate | <10% | ✅ 7% |
| Monthly Cost | <$200 | ✅ $150 |

### Key Dependencies

- **LangGraph** ≥0.5.3 - Enhanced persistence and streaming
- **Qdrant** ≥1.15.0 - Async batch operations and Query API
- **Neo4j** ≥5.28.1 - Latest LTS with Bolt efficiency
- **Redis** ≥6.0.0 - New dialect and client-side caching
- **Sentence Transformers** ≥5.0.0 - v5.0 with SparseEncoder/hybrid
- **OpenAI** ≥1.97.0 - Structured outputs and fine-tuning
- **PyTorch** ≥2.7.1 - Latest compile and quantization (GPU extra)

## 📚 Documentation

- [Architecture Decision Records (ADRs)](docs/adrs/)
- [Product Requirements Document (PRD)](docs/prd.md)
- [API Documentation](docs/api.md)
- [Deployment Guide](docs/deployment.md)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

```bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/codeforge
cd codeforge

# Create feature branch
git checkout -b feature/amazing-feature

# Set up development environment
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Make changes and test
uv run pytest

# Format code
uv run ruff format .

# Submit PR
```

## 📝 Citation

If you use CodeForge AI in your research or project, please cite:

```bibtex
@software{melin2025codeforge,
  author = {Melin, Bjorn},
  title = {CodeForge AI: Autonomous Multi-Agent System for Software Development},
  year = {2025},
  url = {https://github.com/BjornMelin/codeforge},
  version = {0.1.0}
}
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

⭐ **Star us on GitHub** — it helps!

[![GitHub stars](https://img.shields.io/github/stars/BjornMelin/codeforge.svg?style=social)](https://github.com/BjornMelin/codeforge/stargazers)

</div>

codeforge

codeforge Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

codeforge

codeforge Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README