Documentation

Getting Started with RaggieCode

From zero to running RaggieCode on your project in under five minutes. Install, configure your LLM provider, and execute your first automated code change.

Estimated read time: 8 minutes · Updated July 11, 2026

Prerequisites

Before you begin, make sure your system meets the following requirements:

Python 3.10 or higher

Required for modern Python features and dependency compatibility.

pip (latest version)

Python package manager. Upgrade with pip install --upgrade pip.

LLM API key (recommended)

An OpenAI-compatible API key (OpenAI, DeepSeek, OpenRouter, etc.) or a local model via Ollama / vLLM.

git (optional, but recommended)

For cloning the repository and leveraging built-in versioning.

Installation

There are two ways to install RaggieCode. Choose the one that works best for your workflow.

Method 1 — Install directly via pip

The quickest way. Install directly from the GitHub repository:

Terminal 
pip install git+https://github.com/Hussein-L-AlMadhachi/RaggieCode.git

This installs the latest commit from the main branch along with all dependencies (tree-sitter, OpenAI SDK, etc.).

Method 2 — Clone the repository

Recommended if you want to browse the source or contribute:

Terminal 
git clone https://github.com/Hussein-L-AlMadhachi/RaggieCode.git
cd RaggieCode
pip install .

This gives you a local copy you can modify, and pip install . installs it in editable-looking mode (or use pip install -e . for true development mode).

Verify Installation

Check that Raggie installed correctly by running:

Terminal 
raggie --help

You should see the available commands: setup, code, skill, and --version.

Setup Wizard

The raggie setup command launches an interactive wizard that guides you through configuring your LLM provider and agent roles.

raggie setup 
$ raggie setup

  Raggie Setup Wizard
============================================================

  Step 1: Configure your API keys.
  You'll need at least one API key to use Raggie.

  API Keys
  ----------------------------------------
    1. https://api.deepseek.com -> sk-e***************************ed71
    2. https://openrouter.ai/api/v1 -> sk-o**************************58cf
    3. https://api.z.ai/api/paas/v4/ -> 3477*****************************************G2KP
    4. http://localhost:11434/v1/ -> *****

  q. Skip
  1. Add key
  2. Remove key

  Choice: q

  Step 2: Review your agent roles.
  Roles define which model and base URL each agent uses.

  Agent Roles
  ------------------------------------------------------------
    1. code
       Model:          deepseek-v4-flash
       Base URL:       https://api.deepseek.com
       Context Window: 500000
       Prompt:         coder_system_prompt.md
       Reasoning:      off
       Streaming:      off

  q. Exit
  1. Edit role's base URL / model

  Choice: q

============================================================
    Setup complete! You're ready to use Raggie.
    Try: raggie code .
============================================================

Using a local model?

If you choose Ollama or vLLM in step 1, the wizard will prompt you for the base_url (e.g., http://localhost:11434 for Ollama or http://localhost:8000 for vLLM). API key can be left blank for local servers.

What was created

The setup wizard creates ~/.config/raggie/keys.json with your API keys and ~/.config/raggie/roles.json with your provider settings (model, base_url, context_window, reasoning, stream). These files are never shared or transmitted anywhere.

Your First Task

Once setup is complete, you are ready to run RaggieCode on any project. Let us walk through a complete session step by step.

1. Navigate to a Project

Choose any Python project (or any supported language project) and launch RaggieCode:

Terminal 
cd ~/projects/my-python-app
raggie code .

2. Expected Output: Indexing

RaggieCode will parse your project with tree-sitter and build a semantic index. You should see output similar to:

raggie code . 
$ raggie code .
Available chats for role 'code':
--------------------------------------------------
  1. Add input validation to login endpoint...
  2. Refactor the auth middleware...
  3. Create utils/stats.py with calculate_stats...

press ctrl+c to exit at any point
Options: <number> to select, 'n' for new chat, 'del <number>' to delete, 'del all' to delete all
Select a chat: n

============================================================

Raggie Agent (code) v0.1.3 - Interactive Mode
Press Esc followed by Enter to send message, or type 'exit' to quit
--------------------------------------------------

use /help to see all available commands


You:

3. Make a Request

Type a natural language request. For example, ask RaggieCode to add a function:

Chat 
You: Add a function called `calculate_stats` that takes a list of numbers
and returns a dictionary with the mean, median, and standard deviation.
Put it in utils/stats.py.

4. Expected Agent Response

RaggieCode explores the codebase, plans the task, presents a plan for approval, then executes:

Agent 
Agent: Let me explore the codebase to understand what exists before making changes.

    GetFileCodeSemantics(file_path="utils/")
    GetSymbolSourceCode(symbol_name="calculate_stats")

I've checked the project. No utils/stats.py exists yet and no
calculate_stats function is defined anywhere. I'll create it.

    CreateTodoList()
    AddTask(todo_list_id=..., goal="Create utils/stats.py with calculate_stats", ...)
    AddTask(todo_list_id=..., goal="Verify the module imports and runs correctly", ...)

Here is my plan:
  1. Create utils/stats.py with calculate_stats() function
  2. Verify the module imports and runs correctly

Approve this plan? [y/N]: y

    ExecuteNextTask(todo_list_id=...)
    WriteFile(file_path="utils/stats.py", ...)

  Task 1 complete: Created utils/stats.py

    ExecuteNextTask(todo_list_id=...)
    Shell(command="python -c 'from utils.stats import calculate_stats; print(calculate_stats([1,2,3,4,5]))'")
  {'mean': 3.0, 'median': 3, 'std_dev': 1.5811, 'count': 5, 'min': 1, 'max': 5}

  All 2 tasks complete. Module imports and runs correctly.

    ViewChanges(view_type="status")
  Added: utils/stats.py

  Committing via built-in git...
  Done! Created utils/stats.py with calculate_stats().
  The function accepts a list of numbers and returns:
    - mean (arithmetic average)
    - median (middle value)
    - std_dev (population standard deviation)
  type /undo to undo the last code changes

What just happened

  • RaggieCode checked if the function or file already existed
  • Created utils/stats.py with the requested function
  • Planned multi-step work and asked for approval
  • Verified the code works by running it
  • Auto-committed the change to the built-in git repo
  • Presented a clear summary of what was done

Pro tip: single-shot mode

Skip the interactive chat entirely. Run RaggieCode with a --prompt flag for headless execution:

raggie code . --prompt "Add calculate_stats to utils/stats.py"

Configuration Details

RaggieCode stores its configuration in two locations: user-level config and project-level config. Understanding these will help you tailor the agent to your workflow.

~/.config/raggie/roles.json

Global user configuration. Created by raggie setup, editable at any time.

~/.config/raggie/roles.json 
{
  "code": {
    "tools": [
      "ListDir",
      "Shell",
      "TempBackgroundService",
      "ShellKill",
      "WriteFile",
      "ReplaceText",
      "RemoveFile",
      "GetSymbolSourceCode",
      "GetFileCodeSemantics",
      "WalkCallTree",
      "SetSkill",
      "GetSkill",
      "SearchAllFilesContent",
      "WebFetch",
      "WebSearch",
      "DispatchSubagent",
      "CreateTodoList",
      "AddTask",
      "GetTodoList",
      "ApproveTodoList",
      "ExecuteNextTask",
      "MarkTaskComplete",
      "MarkTaskFailed",
      "MarkTaskCancelled",
      "GetActiveTodoList",
      "ViewChanges",
      "AskUser",
      "FileNameSearch",
      "EditSymbol"
    ],
    "model": "",
    "base_url": "",
    "system_prompt_file": "coder_system_prompt.md",
    "context_window": 200000,
    "reasoning": false,
    "stream": false
  }
}

Key fields:

  • model — Any OpenAI-compatible model name (e.g., gpt-4o, deepseek-chat, codellama). Leave empty to be prompted at runtime.
  • base_url — The API endpoint. Set to http://localhost:11434/v1 for Ollama. Leave empty to be prompted at runtime.
  • system_prompt_file — Path to the system prompt file (relative to src/config/).
  • context_window — Maximum context window size in tokens (default: 200000).
  • reasoning — Toggle reasoning output (true/false).
  • stream — Toggle streaming mode (true/false).
  • tools — Array of tool names available to this role.

Project-level: AGENTS.md

Place an AGENTS.md file in your project root to define project-specific conventions, coding standards, and guardrails that the agent reads on every session.

AGENTS.md 
# Project Conventions

## Code Style
- Use type hints for all function signatures
- Max line length: 88 characters
- Use snake_case for functions and variables
- Use PascalCase for classes

## Testing
- All new functions must have unit tests
- Tests go in tests/ directory
- Run tests with: python -m pytest tests/

## Architecture
- Business logic goes in src/service/
- API endpoints go in src/api/
- Data models go in src/models/

Project data directory: .raggie/

When you run raggie code ., RaggieCode creates a .raggie/ directory in your project root. This is automatically added to .gitignore. It contains:

Path Contents Persistent?
.raggie/.code_index.raggie SQLite database with the full semantic code index Yes - persists across sessions
.raggie/.raggie.chat Chat history database Yes - persists across sessions
.raggie/git/ Built-in git repository for undo/redo Yes - every commit is tracked

All data stays local on your machine. Nothing is transmitted except the LLM API calls you explicitly configure.

Troubleshooting

Common issues and their solutions when getting started with RaggieCode.

raggie: command not found

The raggie executable is not on your PATH.

Try these fixes:

  • Ensure Python's bin directory is on your PATH: python -m raggie --help
  • On Linux/macOS, check: export PATH="$HOME/.local/bin:$PATH"
  • Reinstall with: pip install --user git+https://github.com/Hussein-L-AlMadhachi/RaggieCode.git
  • Verify Python version: python --version (must be 3.10+)
No module named raggie

The package did not install correctly, or you are in the wrong virtual environment.

  • Check if installed: pip list | grep raggie
  • Activate the correct virtual environment (conda, venv, etc.)
  • Reinstall: pip install --upgrade --force-reinstall git+https://github.com/Hussein-L-AlMadhachi/RaggieCode.git
Indexing is slow or hangs

The first-time index builds the full semantic database. Large projects with tens of thousands of files may take a moment.

  • Add patterns to .gitignore to exclude node_modules, vendor, or build directories
  • Check CPU usage: indexing uses multiprocessing (one worker per core)
  • Subsequent runs use the cached index and are near-instant
  • If it hangs, delete .raggie/.code_index.raggie and try again
API key not configured

RaggieCode cannot find your API key or LLM configuration.

  • Run raggie setup to configure your provider interactively
  • Check the config file: cat ~/.config/raggie/roles.json
  • Verify the api_key field is not empty (unless using a local model)
  • For local models, ensure base_url points to a running server
The agent does not find my symbols

RaggieCode supports 15 languages. If your language is not listed, symbols will not be indexed.

  • Supported languages: Python, JavaScript, TypeScript, TSX, Go, Rust, C, C++, C#, PHP, Elixir, Zig, Dart, Java, Kotlin
  • Unsupported languages (Ruby, Swift, Lua, etc.) are listed as files but not semantically indexed
  • Files in .gitignore patterns are not indexed at all
  • Delete .raggie/.code_index.raggie and re-run to force a fresh index
The agent is not making changes I expect

The agent may need clearer instructions or additional context.

  • Be specific about which files or functions to modify
  • Create an AGENTS.md file in your project root with conventions
  • Type /undo to revert the last change and try again with different instructions
  • Check the agent's tool calls to see what it looked at before acting
  • Use /status to see the current state if a task was interrupted

Next Steps

Now that you have RaggieCode running, explore its full capabilities:

Architecture Overview

Understand the semantic index, call graph, subagent delegation, and context handover pipeline.

Agent Handover

Learn how RaggieCode preserves task state across context window limits.

GitHub Repository

Browse the source code, open issues, and contribute to the project.

FAQ

Find answers to common questions about data privacy, local models, and more.