https://github.com/iamsr/devlok
tool designed to help you deeply understand your codebase.
https://github.com/iamsr/devlok
ast chromadb electron fastapi langchain react
Last synced: 16 days ago
JSON representation
tool designed to help you deeply understand your codebase.
- Host: GitHub
- URL: https://github.com/iamsr/devlok
- Owner: iamsr
- Created: 2025-01-29T08:44:57.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-10T07:21:52.000Z (4 months ago)
- Last Synced: 2026-05-18T20:37:27.048Z (about 1 month ago)
- Topics: ast, chromadb, electron, fastapi, langchain, react
- Language: Python
- Homepage: https://devlok.devss.io
- Size: 1.97 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
# 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](https://www.electronjs.org/) with [React](https://react.dev/) & [TypeScript](https://www.typescriptlang.org/)
- **Visualization**: [React Flow](https://reactflow.dev/) / [D3.js](https://d3js.org/) (Planned)
- **Styling**: [Tailwind CSS](https://tailwindcss.com/)
- **State Management**: [Zustand](https://github.com/pmndrs/zustand)
- **Code Viewer**: [Monaco Editor](https://microsoft.github.io/monaco-editor/) (Read-only mode)
### Backend (Server)
- **Framework**: [FastAPI](https://fastapi.tiangolo.com/)
- **Language**: Python 3.12+
- **AI/ML**: [LangChain](https://www.langchain.com/), [Ollama](https://ollama.com/), [ChromaDB](https://www.trychroma.com/)
- **Analysis**: [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) for parsing
## 📦 Prerequisites
Before getting started, ensure you have the following installed:
- **Node.js**: v18 or later ([Download](https://nodejs.org/))
- **pnpm**: Package manager for Node.js (`npm install -g pnpm`)
- **Python**: 3.12 (not 3.13+) ([Download](https://www.python.org/downloads/))
- **Poetry**: Python dependency manager (`pip install poetry` or see [docs](https://python-poetry.org/docs/#installation))
- **Ollama**: For running local LLMs ([Download](https://ollama.com/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:
```bash
# 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
```bash
git clone https://github.com/yourusername/devlok.git
cd devlok
```
#### 2. Backend Setup
Navigate to the backend directory and install dependencies:
```bash
cd apps/backend
poetry install
```
Start the backend server:
```bash
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:
```bash
cd apps/client
pnpm install
```
Start the Electron application:
```bash
pnpm dev
```
The Electron app will launch automatically.
#### 4. Ollama Setup
Make sure Ollama is running with a model installed:
```bash
# 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
```bash
# Terminal 1: Start backend
make dev-backend
# Terminal 2: Start frontend
make dev-frontend
```
Or use a single command:
```bash
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
```bash
# 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:
```bash
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:
```bash
make install-backend
```
And verify Ollama is running:
```bash
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](CONTRIBUTING.md) for guidelines.
## 📄 License
[MIT](LICENSE)