codelectus

Codelectus: On-device AI code review that runs on the laptop you already own. No API keys. No GPU. Just a 2.3 GB model that gives every developer everywhere senior-level code reviews offline.

Comment

Codelectus: AI-Powered Code Review for the Africa Deep Tech Challenge 2026

Codelectus is a submission for the Africa Deep Tech Challenge (ADTC) 2026: The Laptop LLM Challenge — an engineering-first competition to make useful language-model applications run well on the computers Africans already own: mid- and low-end commodity laptops with 8 GB RAM and integrated graphics.

Problem Domain: Coding Assistants — code generation, debugging help, and programming tutoring across common languages.

Codelectus addresses the core challenge of the ADTC 2026 by building an on-device AI code review assistant that runs efficiently on the ADTC Standard Laptop (8 GB DDR4, integrated graphics, no discrete GPU). It leverages local LLMs via Ollama and quantized models to provide intelligent code reviews without cloud dependencies, making AI-powered development accessible to developers across Africa and other resource-constrained environments.

The Problem: AI Access Economics in Africa

Africa is not excluded from the language model revolution — the bottleneck is access economics. Cloud-hosted LLMs require:

  • API fees that are prohibitive for students and small teams
  • Stable fiber internet connectivity
  • Sustained electricity for cloud round-trips

For a university student in Lagos, an extension officer in Arusha, or a small-business owner in Dakar, these are not minor frictions — they are blockers.

How Codelectus Solves This

Codelectus brings AI code review fully on-device using a custom fine-tuned Qwen3-4B model (qwen3-4b-codereview-taid, Q4_K_M quantization, ~2.3 GB):

Challenge Codelectus Solution
Cloud API costs Runs local LLM via Ollama (custom mrlectus model) — $0 inference cost
Internet dependency Fully offline-capable; reviews code locally without network calls
Hardware constraints Optimized for 8 GB RAM / integrated graphics — 4-bit quantization (Q4_K_M), KV cache management
Latency Sub-second response for typical PRs via local inference
Privacy Code never leaves the developer's machine

ADTC 2026 Alignment

Problem Domain: Coding Assistants ✓

Codelectus is purpose-built for the Coding Assistants domain — providing code review, debugging assistance, and programming tutoring through AI.

Technical Feasibility & Implementation

  • On-device inference: Integrates Ollama for local LLM execution with quantized GGUF models
  • Custom model: mrlectus — fine-tuned Qwen3-4B (qwen3-4b-codereview-taid.Q4_K_M.gguf) specialized for code review
  • Resource optimization: 4-bit quantization (Q4_K_M), context window management, streaming responses
  • Offline-first architecture: Core review functionality works without internet; cloud sync is optional

Model Accuracy & Quality

  • Single-model excellence: One optimized model (mrlectus) handles all review types via prompt engineering and structured output schemas
  • Context-aware reviews: Ingests repository context (AGENTS.md, CLAUDE.md, .cursorrules, README) for tailored feedback
  • Iterative improvement: Users can reply to AI comments to teach the model about their codebase

Model Throughput Performance

  • Target: 15+ tokens/second on ADTC Standard Laptop (Intel Core i5 10th–12th gen / AMD Ryzen 5 3000–5000, 8 GB RAM)
  • Optimizations: llama.cpp backend via Ollama, KV cache reuse, batched inference for multi-file reviews

Model Efficiency

  • Memory budget: < 7 GB peak RAM (leaving headroom for OS + browser + IDE)
  • Quantization: 4-bit (Q4_K_M) as default; supports Q8_0 for higher quality when RAM allows
  • Dynamic model loading: Unloads models when not in use via Ollama's keep-alive configuration

African Use Case Bonus

  • Local-first philosophy: Designed for intermittent connectivity, expensive data, and unreliable power
  • Educational impact: Helps junior developers across Africa get senior-level code review feedback without mentorship access
  • Open source: Fully open, hackable, and deployable on any hardware — no vendor lock-in

Hardware & Thermal Penalties

  • Thermal management: Streaming responses prevent sustained 100% CPU; configurable inference threads
  • No OOM crashes: Graceful degradation with clear error messages when memory pressure detected

Live Demo

Design and Architecture

Codelectus follows a hybrid architecture: a cloud-connected dashboard for settings/analytics, with on-device AI inference for the actual code reviews. This ensures the core value proposition (AI code review) works offline on commodity hardware.

Frontend (Dashboard)

  • Built with React 19 and TypeScript.
  • TanStack Start (Vite + SSR) for fast development and optimized builds.
  • TanStack Router for type-safe client-side routing with SSR.
  • TanStack Query for efficient data fetching, caching, and optimistic updates.
  • Tailwind CSS v4 for utility-first UI development.
  • React Compiler for automatic performance optimizations.
  • shadcn/ui + Radix UI for accessible, customizable components.

Backend (Cloud Dashboard)

  • Deployed on Cloudflare Workers (edge runtime, global distribution).
  • Cloudflare Queues for asynchronous task processing (webhook handling, background jobs).
  • Hono as the lightweight web framework for Workers.
  • oRPC for end-to-end type-safe APIs (client ↔ server).

Database

  • Neon (PostgreSQL) serverless database for user settings, review history, analytics.
  • Drizzle ORM for type-safe database interactions and migrations.

AI Integration (On-Device First)

  • Ollama for local LLM inference — runs quantized GGUF models on CPU/integrated GPU.
  • Vercel AI SDK (ollama-ai-provider-v2) for unified model interface.
  • Custom model: mrlectus — a fine-tuned Qwen3-4B model (qwen3-4b-codereview-taid.Q4_K_M.gguf, ~2.3 GB) specialized for code review, loaded from local GGUF via Modelfile.
  • Single-model design: One optimized model handles all review types (general, ultra, auto-approve, PR description) via prompt engineering and structured output.
  • Context ingestion: Automatically reads AGENTS.md, CLAUDE.md, .cursorrules, README.md, and custom instructions.

Authentication

  • Better Auth with GitHub OAuth for seamless developer onboarding.
  • Octokit for GitHub API interactions (webhooks, PR data, comments).

On-Device Execution Flow

1. Developer pushes code → GitHub webhook → Cloudflare Queue
2. Queue triggers local review agent (via CLI or background service)
3. Agent fetches PR diff → Runs local LLM via Ollama → Posts review comments
4. Results synced to dashboard for analytics (optional, async)

Features

Core Review Features (On-Device)

  • AI Code Review Agent (general-review.tsx): Automated PR reviews with configurable sensitivity (Low/Medium/High), incremental commit reviews, draft PR reviews, and custom instructions.
  • Ultrareview (ultrareview.tsx): Deep architectural and performance analysis — uses the same mrlectus model with extended prompts for comprehensive reviews (Manual/Automatic triggers).
  • Auto-Approve (auto-approve.tsx): Shadow mode (shows approval without submitting) or Live mode (actual GitHub approvals) with policy-based gating.
  • AI PR Descriptions (pr-description.tsx): Generates comprehensive PR descriptions from diffs, with custom instruction support.

All features use the single mrlectus model (qwen3-4b-codereview-taid) via prompt engineering and structured output schemas — no model switching required.

Dashboard & Analytics

  • Analytics Dashboard (analytics/index.tsx): KPIs (PRs reviewed, bugs caught, time saved), recent reviews feed with findings count, repository breakdown with per-repo stats.
  • Review Settings (review/index.tsx): Unified settings panel with tabs for all review modes, real-time updates via TanStack Query optimistic updates.

Knowledge & Documentation

  • AI Wiki (wiki/index.tsx): Generates and serves AI-powered documentation for any connected repository. Searchable repo cards with one-click wiki generation.

Developer Experience

  • GitHub Integration: @codelectus-dev-ai mention to retrigger reviews, reply to comments to teach the AI.
  • Context Files: Auto-detects AGENTS.md, CLAUDE.md, .cursorrules, README.md, and custom instructions.
  • Offline-First: Core review runs locally via Ollama — no cloud dependency for inference.

ADTC 2026 Submission Requirements

This submission includes:

  • ✅ Open Source GitHub Repo: This repository
  • ✅ Comprehensive Project Report: This README + inline documentation
  • ✅ Problem Definition & Context: Section above on "AI Access Economics in Africa"
  • ✅ Identified Constraints: 8 GB RAM, integrated graphics, no discrete GPU, intermittent connectivity
  • ✅ Design Alternatives & Decisions: Hybrid cloud/on-device architecture, Ollama for local inference, model routing strategy
  • ✅ Tools & Justification: Ollama (llama.cpp), Vercel AI SDK, TanStack ecosystem, Cloudflare Workers, Drizzle ORM
  • ✅ Performance Tests & Benchmarks: See BENCHMARKS.md for ADTC Standard Laptop results
  • ✅ Screenshots/Video: See docs/demo.mp4 (max 2 min) showing on-device review flow

Getting Started

Prerequisites

  • pnpm (package manager)
  • Ollama (for local LLM inference) — Install Ollama
  • Node.js 20+ (for the dashboard)

Quick Start (Dashboard Only)

For the cloud-connected dashboard (settings, analytics, wiki):

  1. Clone the repository:

    git clone <repository-url>
cd adtc-2026-submission/codelectus

  2. Install dependencies:

    pnpm install

  3. Set up environment variables: Create a .env file in the codelectus directory with:

    # Database
DB_URL="postgresql://..."

# GitHub OAuth
GITHUB_CLIENT_ID="..."
GITHUB_CLIENT_SECRET="..."

# Better Auth
BETTER_AUTH_SECRET="..."
BETTER_AUTH_URL="http://localhost:3000"

# Cloudflare (for Workers deployment)
CLOUDFLARE_ACCOUNT_ID="..."
CLOUDFLARE_DATABASE_ID="..."

  4. Run the development server:

    pnpm dev

On-Device AI Review Setup (ADTC 2026 Core)

Codelectus uses a custom fine-tuned Qwen3-4B model (qwen3-4b-codereview-taid) optimized for code review, distributed as a GGUF file. This model is downloaded and loaded into Ollama locally — no cloud model registry required.

  1. Install and start Ollama:

    # macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh
ollama serve

  2. Download and create the custom model:

    # From the repository root (adtc-2026-submission/)
./download_model.sh

# This downloads qwen3-4b-codereview-taid.Q4_K_M.gguf (~2.3 GB) to ./model/
# Then create the model in Ollama:
ollama create mrlectus -f Modelfile

    The Modelfile simply references the local GGUF:

    FROM ./model/qwen3-4b-codereview-taid.Q4_K_M.gguf

  3. Verify the model is available:

    ollama list
# Should show: mrlectus  latest  2.3 GB

  4. Run the review agent (processes webhook events locally via Cloudflare Workers dev):

    # From codelectus/ directory
pnpm dev
# In another terminal, trigger a test webhook or push to a connected repo

    The queue consumer runs as part of wrangler dev (invoked by pnpm dev). It listens to the codelectus queue and processes reviews using the local Ollama model.

Model Details:

  • Base: Qwen3-4B
  • Fine-tune: Code review specialized (TAID dataset)
  • Quantization: Q4_K_M (4-bit, ~2.3 GB)
  • Context: 32K tokens
  • Target hardware: ADTC Standard Laptop (8 GB RAM, integrated graphics)

ADTC Standard Laptop Validation

Test your setup matches the competition hardware profile:

# Run the ADTC profiler (from https://github.com/Africa-Deep-Tech-Foundation/adtc-profiler)
./adtc-profiler --model mrlectus --prompt "Review this PR for bugs"

Expected targets on ADTC Standard Laptop (i5-10th/12th gen or Ryzen 5 3000-5000, 8 GB RAM) with mrlectus (qwen3-4b-codereview-taid.Q4_K_M):

  • Throughput: ≥ 15 tokens/sec
  • Peak RAM: ≤ 7 GB (model ~2.3 GB + KV cache + OS overhead)
  • Thermal: No throttling, temp ≤ 85°C

Deployment

Cloud Dashboard (Cloudflare Workers)

The dashboard, analytics, wiki, and settings UI deploy to Cloudflare's global edge network:

  1. Build the project:

    pnpm build

  2. Deploy to Cloudflare:

    pnpm deploy

    Requires wrangler configured with your Cloudflare account. Sets up Workers, Queues, D1/KV, and custom domains.

On-Device Review Agent (ADTC 2026 Core)

The AI review engine runs locally on the developer's machine — no cloud deployment needed for inference:

Platform Installation
Linux (Ubuntu 22.04+) `curl -fsSL https://ollama.com/install.sh \
macOS (Apple Silicon/Intel) brew install ollama && ollama serve
Windows (WSL2 recommended) Download from ollama.com

Model setup (run once):

# From repository root
./download_model.sh
ollama create mrlectus -f Modelfile

Run locally (ADTC 2026 evaluation):

# From codelectus/ directory
pnpm dev
# This starts the Cloudflare Worker + queue consumer locally
# The consumer uses the local Ollama model (mrlectus) for inference

For ADTC 2026 evaluation: The review agent runs on the ADTC Standard Laptop (8 GB RAM, integrated graphics, Ubuntu 22.04) using the custom mrlectus model (qwen3-4b-codereview-taid.Q4_K_M, ~2.3 GB). No GPU, no cloud, no API keys required.

Hybrid Architecture Note

  • Dashboard = Cloud (Cloudflare Workers) — for settings, analytics, team management
  • Review Engine = Local (Ollama + CLI agent) — for actual AI inference
  • Sync = Async via GitHub webhooks → Cloudflare Queues → Local agent polling

This separation is intentional: it keeps AI inference free, private, and offline-capable while providing a polished cloud dashboard for collaboration.

Built With

Share this project:

Updates