Reference

Configuration

Everything you need to configure RaggieCode: user config directory layout, role definitions, project conventions with AGENTS.md, ignore file enforcement, and step-by-step guides for running local AI with Ollama, vLLM, and LM Studio.

Estimated read time: 9 minutes · Updated July 12, 2026

User Config Directory

All user-specific configuration lives in ~/.config/raggie/. On first run, the setup wizard creates this directory and copies default files from the package.

~/.config/raggie/ 
~/.config/raggie/
├── keys.json     # API keys (base_url -> key mappings)
├── roles.json    # Role definitions (copied from src/config/ on first run)
└── tools.json    # Tool definitions (copied from src/config/ on first run)
File Purpose Managed by
keys.json API key per base URL. Supports the "nokey" convention for local servers raggie keys, raggie setup
roles.json Agent role definitions: model, base URL, tools, system prompt, and runtime settings raggie roles, raggie setup
tools.json Tool definitions sent to the LLM for function calling. Generally should not be edited manually Copied from package on first run

roles.json

Defines your agent roles. Each role specifies which model to use, where the API endpoint is, what tools are available, and how the agent should behave at runtime. You can manage roles interactively with raggie roles, or edit the file directly.

Example roles.json:

~/.config/raggie/roles.json 
{
  "code": {
    "tools": ["UglyWholeFileContentDump", "Shell", "WriteFile", "..."],
    "model": "deepseek-v4-flash",
    "base_url": "https://api.deepseek.com",
    "system_prompt_file": "coder_system_prompt.md",
    "context_window": 500000,
    "reasoning": false,
    "stream": false
  }
}

Fields Reference

Field Type Description
tools array List of tool names available to this role. Must match names defined in tools.json
model string The model identifier to use for API calls. Must match what the provider expects (e.g. "deepseek-v4-flash", "qwen2.5:14b")
base_url string The API endpoint URL. The OpenAI client appends /chat/completions. Must include trailing /v1/ for OpenAI-compatible endpoints
system_prompt_file string Filename (relative to src/config/) of the Markdown file used as the base system prompt for this role
context_window integer Maximum context window size in tokens. Controls when the automatic session handover triggers. Set to your model's actual context length
reasoning boolean Enable reasoning output from the LLM (if supported). Toggle mid-session with /reasoning on|off
stream boolean Enable streaming responses. Set to false for local models where streaming with tool calls can be unreliable. Toggle mid-session with /streaming on|off

Runtime persistence

Four fields in roles.json are writable from within a chat session using in-chat commands: /streaming, /reasoning, /windowSize, and /globalTodo. Changes take effect on the next message and survive across sessions.

Multiple Roles

You can define multiple roles in roles.json, each with different models or configurations. Use them by passing the role name to raggie code:

Terminal 
raggie code .             # uses the "code" role (default)
raggie reviewer .         # uses a custom "reviewer" role

AGENTS.md

Place a file called AGENTS.md in your project root. Its contents are automatically appended to the agent's system prompt every time it starts. This is the primary mechanism for defining project-specific conventions that the agent should follow.

Example AGENTS.md:

AGENTS.md 
# Project Conventions
- Use TypeScript for all new files
- Tests go in a __tests__/ directory
- Follow the existing ESLint config
- Never use `any` in TypeScript . use `unknown` instead
- All API responses should use the `ApiResponse` wrapper

How It Stacks

At startup, the agent builds its system prompt in this order:

  1. Role system prompt .; The base prompt file defined by system_prompt_file in roles.json
  2. Date, directory, and host info .; Current date, working directory, and host system details
  3. Skill summaries .; Brief one-line summaries of all skills for the role (full content loaded on demand via GetSkill)
  4. AGENTS.md .; The contents of your project's AGENTS.md file, if it exists

AGENTS.md is appended after skills, so it can override or extend skill instructions for project-specific needs. This is the last layer before the conversation begins.

Tips for AGENTS.md

  • Keep it concise. The entire file goes into the system prompt on every session, so every line costs tokens
  • Focus on conventions the agent wouldn't infer from the codebase itself: naming patterns, library preferences, architectural rules
  • Use Markdown formatting. The LLM understands headings, lists, and code blocks
  • AGENTS.md is project-specific. For global persistent instructions, use the skills system instead

.gitignore & .aiignore

Raggie uses ignore patterns to determine which files are off-limits. This applies to both code indexing (what the agent knows about) and file access (what the agent can read, write, or modify). The enforcement is strict: ignored files are invisible to the agent.

How enforcement works

Scenario Behavior
Only .gitignore exists .gitignore is used for both code indexing and file access enforcement
.aiignore exists .aiignore is used instead of .gitignore for both indexing and file access. Your git configuration is ignored entirely for agent purposes
Neither exists Hardcoded fallback exclusions apply: .raggie, .git, .venv, __pycache__, build, dist, .egg-info, and common binary extensions

Example .aiignore:

.aiignore 
# Prevent the agent from touching these
.env
*.log
node_modules/
secrets/
credentials.json
migrations/

Why use .aiignore?

Sometimes you want git to track a file but don't want the AI agent touching it. Or you want git to ignore a file but still want the agent to see it. .aiignore decouples these concerns.

Lock down sensitive files

Secrets, credentials, and environment files that should never be read by the agent, even if they're in version control as templates.

Let the agent see ignored files

Have the agent read build artifacts or generated files that git ignores, without modifying .gitignore.

.aiignore uses the same pattern syntax as .gitignore. Comments, wildcards, negations, and directory patterns all work as expected.

What the agent cannot do with ignored files

  • Read .; UglyWholeFileContentDump and GetFileCodeSemantics will error on ignored paths
  • Write .; WriteFile refuses to create ignored files
  • Modify .; ReplaceText and EditSymbol refuse to touch ignored files
  • Delete .; RemoveFile refuses to delete ignored files
  • Index .; The code indexer skips ignored files entirely

Using Local AI

Raggie works with any OpenAI-compatible local LLM server. Below are step-by-step setup guides for the three most popular options: Ollama, vLLM, and LM Studio. All three follow the same pattern: start the server, configure roles.json and keys.json, then run raggie code.

Ollama

Ollama runs models locally with a built-in OpenAI-compatible endpoint. It's the easiest way to get started with local AI.

1 Install and pull a model

Follow the instructions at ollama.com to install. Then pull a model that supports tool calling (not all models do . Qwen2.5 and Llama 3.1 are known to work well).

Terminal 
ollama pull qwen2.5:14b
# or
ollama pull llama3.1:8b

Start the server (it usually starts automatically after installation):

ollama serve

2 Configure roles.json

Edit ~/.config/raggie/roles.json. Set stream to false and match context_window to your model's actual context length.

~/.config/raggie/roles.json 
{
  "code": {
    "model": "qwen2.5:14b",
    "base_url": "http://localhost:11434/v1/",
    "tools": ["..."],
    "system_prompt_file": "coder_system_prompt.md",
    "context_window": 32768,
    "reasoning": false,
    "stream": false
  }
}

3 Set the API key to "nokey"

Raggie sees "nokey" and passes an empty API key to the OpenAI client, which Ollama ignores.

~/.config/raggie/keys.json 
{
  "http://localhost:11434/v1/": "nokey"
}

4 Run Raggie

Terminal 
raggie code myproject

vLLM

vLLM is a high-throughput inference engine with an OpenAI-compatible server. It requires more setup than Ollama but offers better performance for larger models.

1 Install vLLM

Terminal 
pip install vllm

2 Start the server with tool calling enabled

The --enable-auto-tool-choice and --tool-call-parser flags are required for Raggie to work. Use hermes for most models.

Terminal 
vllm serve Qwen/Qwen2.5-14B-Instruct --enable-auto-tool-choice --tool-call-parser hermes

3 Configure roles.json

~/.config/raggie/roles.json 
{
  "code": {
    "model": "Qwen/Qwen2.5-14B-Instruct",
    "base_url": "http://localhost:8000/v1/",
    "tools": ["..."],
    "system_prompt_file": "coder_system_prompt.md",
    "context_window": 32768,
    "reasoning": false,
    "stream": false
  }
}

4 Set the API key to "nokey"

~/.config/raggie/keys.json 
{
  "http://localhost:8000/v1/": "nokey"
}

5 Run Raggie

Terminal 
raggie code myproject

LM Studio

LM Studio provides a desktop GUI for running local models with an OpenAI-compatible server. No command line needed for model management.

1 Install and download a model

Install LM Studio from lmstudio.ai. Download a model that supports tool calling (Qwen2.5, Llama 3.1, or Mistral are good choices).

2 Start the local server

In LM Studio, go to the "Local Server" tab, load your model, and click "Start Server". The default endpoint is http://localhost:1234/v1/.

3 Configure roles.json

The model name must match what LM Studio shows as the loaded model identifier. It's typically the Hugging Face model name (e.g. "qwen2.5-14b-instruct").

~/.config/raggie/roles.json 
{
  "code": {
    "model": "qwen2.5-14b-instruct",
    "base_url": "http://localhost:1234/v1/",
    "tools": ["..."],
    "system_prompt_file": "coder_system_prompt.md",
    "context_window": 32768,
    "reasoning": false,
    "stream": false
  }
}

4 Set the API key to "nokey"

~/.config/raggie/keys.json 
{
  "http://localhost:1234/v1/": "nokey"
}

5 Run Raggie

Terminal 
raggie code myproject

General Notes for Local AI

These notes apply regardless of which local server you use. Keep them in mind when configuring your setup.

Tool Calling Is Required

Raggie relies on function/tool calling to operate. Not all models support this. Known good options include Qwen2.5 (7B+), Llama 3.1 (8B+), and Mistral (7B+). If the model doesn't support tool calls, Raggie won't be able to use any of its 31 tools . it will only be able to generate text responses.

Context Window

Set context_window in roles.json to match your model's actual context length. This controls when the automatic session handover kicks in:

  • Too high: The handover never triggers, and you get API errors when the context fills up
  • Too low: The handover triggers too often, wasting tokens on unnecessary handover documents
  • Just right: The agent hands over smoothly before hitting the context limit

For Qwen2.5:14B, the context window is 32,768 tokens. For Llama 3.1:8B, it's 128,000 tokens. Check your model's documentation for its specific limit.

Streaming

Set "stream": false for local models. Streaming with tool calling can be unreliable with some local servers . the streamed chunks may arrive in an order that the OpenAI client cannot properly reassemble with tool call blocks. Setting it to false means the agent waits for the full response before processing, which is more reliable for local setups.

The "nokey" Convention

Any base_url in keys.json with the value "nokey" tells Raggie to skip authentication and pass an empty API key to the OpenAI client. This is the standard pattern for all local servers:

~/.config/raggie/keys.json 
{
  "http://localhost:11434/v1/": "nokey",
  "http://localhost:8000/v1/": "nokey",
  "http://localhost:1234/v1/": "nokey"
}

You can have multiple "nokey" entries alongside real API keys for cloud providers. Raggie matches by base_url, so the correct key is used for each role.