DevLok - Your AI Codebase Explainer

DevLok is an AI-powered developer tool designed to help you deeply understand your codebase. It combines a modern interface with a powerful local Python backend capable of leveraging Large Language Models (LLMs) to analyze, explain, and visualize your project's architecture and logic.

🚀 Key Features

• Deep Codebase Understanding: Uses Tree-sitter and LangChain to parse and semantically index your entire project.
• AI-Powered Explanations: Ask questions about your code, data flow, or architecture and get context-aware answers from local LLMs (via Ollama).
• Interactive Visualizations: Visualize dependencies, call graphs, and module structures to grasp complex systems quickly.
• Local-First Privacy: All analysis and AI processing happens locally on your machine, ensuring your code never leaves your environment.

🛠 Tech Stack

Frontend (Client)

• Framework: Electron with React & TypeScript
• Visualization: React Flow / D3.js (Planned)
• Styling: Tailwind CSS
• State Management: Zustand
• Code Viewer: Monaco Editor (Read-only mode)

Backend (Server)

• Framework: FastAPI
• Language: Python 3.12+
• AI/ML: LangChain, Ollama, ChromaDB
• Analysis: Tree-sitter for parsing

📦 Prerequisites

Before getting started, ensure you have the following installed:

• Node.js: v18 or later (Download)
• pnpm: Package manager for Node.js (npm install -g pnpm)
• Python: 3.12 (not 3.13+) (Download)
• Poetry: Python dependency manager (pip install poetry or see docs)
• Ollama: For running local LLMs (Download)
• Make: Build automation tool (usually pre-installed on macOS/Linux)

🏁 Getting Started

Quick Start with Makefile

The easiest way to get started is using the provided Makefile:

# Clone the repository
git clone https://github.com/yourusername/devlok.git
cd devlok

# Install all dependencies (backend + frontend)
make install

# Start both backend and frontend in development mode
make dev

That's it! The application should now be running.

Manual Setup

If you prefer to set up manually or want more control:

1. Clone the repository

git clone https://github.com/yourusername/devlok.git
cd devlok

2. Backend Setup

Navigate to the backend directory and install dependencies:

cd apps/backend
poetry install

Start the backend server:

poetry run dev

The backend API will be available at http://localhost:4000

3. Frontend Setup

In a new terminal, navigate to the client directory and install dependencies:

cd apps/client
pnpm install

Start the Electron application:

pnpm dev

The Electron app will launch automatically.

4. Ollama Setup

Make sure Ollama is running with a model installed:

# Pull a recommended model (e.g., llama2)
ollama pull llama2

# Or use a larger model for better results
ollama pull codellama

🔧 Available Make Commands

Here are all available commands in the Makefile:

Installation & Setup

• make install - Install all dependencies (backend + frontend)
• make install-backend - Install only backend dependencies
• make install-frontend - Install only frontend dependencies
• make setup-ollama - Pull recommended Ollama model (llama2)

Development

• make dev - Start both backend and frontend in development mode
• make dev-backend - Start only the backend server
• make dev-frontend - Start only the Electron app
• make dev-parallel - Start both services in parallel (requires parallel or concurrently)

Building

• make build - Build the Electron application
• make build-mac - Build for macOS
• make build-win - Build for Windows
• make build-linux - Build for Linux

Code Quality

• make lint - Run linter on frontend code
• make format - Format frontend code with Prettier
• make typecheck - Run TypeScript type checking

Testing

• make test-backend - Run backend tests

Cleaning

• make clean - Remove all dependencies and build artifacts
• make clean-backend - Clean only backend dependencies
• make clean-frontend - Clean only frontend dependencies

Utilities

• make help - Display all available commands

📝 Development Workflow

Starting Development

# Terminal 1: Start backend
make dev-backend

# Terminal 2: Start frontend
make dev-frontend

Or use a single command:

make dev

Making Changes

1. Frontend changes: Hot reload is enabled, changes will reflect automatically
2. Backend changes: The server will auto-reload on file changes

Building for Production

# Build for your current platform
make build

# Or build for a specific platform
make build-mac    # macOS
make build-win    # Windows
make build-linux  # Linux

🐛 Troubleshooting

Electron fails to start

If you see an error like "Electron failed to install correctly", run:

make fix-electron

This happens because pnpm's build script restrictions. The fix-electron command manually runs the installation scripts that were blocked.

Backend server won't start

Make sure you've run:

make install-backend

And verify Ollama is running:

ollama list

Port already in use

If port 4000 or 5173 is already in use, stop the conflicting service or modify the port in the respective configuration files:

• Backend: apps/backend/main.py
• Frontend: apps/client/electron.vite.config.ts

📂 Project Structure

devlok/
├── apps/
│   ├── client/          # UI for visualization and chat
│   └── backend/         # Analysis engine and AI server
├── docs/                # Documentation
└── ...

🤝 Contributing

See CONTRIBUTING.md for guidelines.

📄 License

MIT