Getting Started

Get Codumentor up and running in minutes. This guide covers the fastest paths to your first conversation.

Option 1: Portable Download (Recommended)

Download the pre-built executable from the releases page.

Linux

chmod +x codumentor
./codumentor

Windows

codumentor.exe

On first run, Codumentor looks at the current directory and offers a short menu of setup options before creating codumentor.yaml:

Single-repo — when you're inside a lone git repo or a plain directory, the config is written alongside your code and the agent treats that directory as the project.
Multi-repo workspace — when sibling git repos or git sub-repos are detected, the config is written to the parent/current directory and lists all of them.

A sensible default is pre-selected for the situation, but you can always pick the other option. Once the config is created, Codumentor begins ingesting the repositories listed in it. When ingestion completes, the terminal UI launches and drops you into an interactive session.

Option 2: From Source

Prerequisites

Python 3.8 -- 3.12
Git
An API key from an OpenAI-compatible provider (e.g. OpenAI, Google Gemini, OpenRouter)

Setup

# Clone the repository
git clone https://gitea.ardinsys.hu/kschaffer/Codumentor.git
cd Codumentor

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # Linux / macOS
# .venv\Scripts\activate         # Windows

# Install dependencies
pip install -r requirements.txt

Configure

Set your API key as an environment variable:

export OPENAI_API_KEY="sk-..."

Create a codumentor.yaml in the project root with the repositories you want to index:

repos:
  - "https://github.com/your-org/your-repo.git"
  - "/path/to/local/repo"

models:
  embedding: "text-embedding-004"
  agent: "gemini-2.0-flash"

Ingest and Chat

# Index your repositories
python -m codumentor.cli.main ingest

# Launch the terminal UI (default with no subcommand)
python -m codumentor.cli.main

Quick Query

Ask a single question without entering the interactive TUI (print mode, -p):

python -m codumentor.cli.main -p "What does the AuthMiddleware class do?"

Web UI

Codumentor includes a React-based web interface with streaming responses, tool visualization, and plugin support.

# Build the UI (first time only)
cd ui && npm install && npm run build && cd ..

# Start the API server
python -m codumentor.cli.main api

Open http://127.0.0.1:2638/app in your browser.

Next Steps

CLI Reference -- All commands and options
Web UI -- Web interface details, URL routing, and tool approvals
Configuration -- Customize models, repos, chunking, and more
Plugins -- Enable web search, memory, metrics, and other extensions
Architecture Overview -- How the system fits together