### Manual Implementation Guide Example

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/planning-workflow.md

Shows how to use RA.Aid to create detailed guides for manual implementation. Generate a comprehensive plan and then extract it as a step-by-step guide.

```bash
# 1. Generate comprehensive plan
ra-aid -m "Set up a new React project with TypeScript, ESLint, and testing" --research-and-plan-only

# 2. Extract as implementation guide
ra-aid extract-last-plan > react-setup-guide.md

# 3. Follow the guide manually, step by step
```

--------------------------------

### Start Local Development Server

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/README.md

Starts a local development server. Changes are reflected live without restarting.

```bash
yarn start
```

--------------------------------

### Using Reasoning Assistance with Specific Models

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/configuration/reasoning-assistance.md

Example of enabling reasoning assistance and specifying an expert model (qwen-qwq-32b) to guide the main agent (qwen-32b-coder-instruct) for a task.

```bash
ra-aid --model qwen-32b-coder-instruct --expert-model qwen-qwq-32b --reasoning-assistance -m "Create a simple web server in Python"
```

--------------------------------

### Install and List Ollama Models

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/configuration/ollama.md

Verify Ollama installation and list available models. Pull specific models to prepare for use with RA.Aid.

```bash
ollama list
```

```bash
ollama pull justinledwards/mistral-small-3.1-Q6_K
ollama pull qwq:32b
```

--------------------------------

### Install and Run RA.Aid

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/intro.md

Install RA.Aid using pip and set up necessary API keys for AI models like Gemini. Then, run RA.Aid from the command line to perform development tasks.

```bash
pip install ra-aid

export GEMINI_API_KEY='your_gemini_api_key'
export TAVILY_API_KEY='your_tavily_api_key'

ra-aid -m "Add input validation to the login form"
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/README.md

Run this command to install project dependencies using Yarn.

```bash
yarn
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

Install the project's development dependencies using pip.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Install RA.Aid with pip

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/installation.md

Install RA.Aid using pip. Note: For Python 3.13+, uv installation is recommended.

```bash
pip install ra-aid
```

--------------------------------

### Install RA.Aid with Homebrew on macOS

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/installation.md

Install RA.Aid on macOS using Homebrew by tapping the repository and then installing the package.

```bash
brew tap ai-christianson/homebrew-ra-aid
```

```bash
brew install ra-aid
```

--------------------------------

### Install RA.Aid via pip or uv

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Install RA.Aid using pip or uv. Ensure Python 3.8+ is used, with Python 3.12 recommended. After installation, set the necessary API keys for LLM providers.

```bash
# Install via pip (Python 3.8+, recommend 3.12)
pip install ra-aid

# Or via uv
uv venv -p 3.12 && source .venv/bin/activate
uv pip install ra-aid
```

--------------------------------

### Install RA.Aid in Development Mode

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/contributing.md

Install the RA.Aid package in editable mode for development.

```bash
pip install -e .
```

--------------------------------

### Team Planning and Documentation Example

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/planning-workflow.md

Demonstrates generating plans for team review and collaboration. The generated plan can be shared as a markdown file for discussion and approval.

```bash
# Generate plan for team review
ra-aid -m "Migrate our authentication system from JWT to OAuth2" --research-and-plan-only

# Extract and share with team
ra-aid extract-last-plan > migration-proposal.md
# (Share migration-proposal.md with your team for review)
```

--------------------------------

### Generate and Extract Database Migration Plan

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/planning-workflow.md

This example shows how to generate a plan for a database migration, extract it to a file, and also extract the associated research notes for context.

```bash
# Generate migration plan
ra-aid -m "Migrate user table to add email verification fields" --research-and-plan-only
```

```bash
# Extract and review
ra-aid extract-last-plan > db-migration-plan.md
```

```bash
# Extract research for additional context
ra-aid extract-last-research-notes > migration-research.md
```

--------------------------------

### Review and Approve Workflow Example

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/planning-workflow.md

Demonstrates the common workflow of generating a plan, extracting it for review, and then executing the task if satisfied. This ensures the AI's approach is sound before implementation.

```bash
# 1. Generate the plan
ra-aid -m "Refactor my_script.py to be more modular" --research-and-plan-only

# 2. Extract and review the plan
ra-aid extract-last-plan > refactor-plan.md
# (Review the plan in your editor)

# 3. If satisfied, execute the same task without the flag
ra-aid -m "Refactor my_script.py to be more modular"
```

--------------------------------

### Install RA.Aid with uv

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/installation.md

Use uv to create a Python 3.12 virtual environment and install RA.Aid. This method is recommended for Python 3.13+ due to compatibility.

```bash
uv venv -p 3.12
```

```bash
source .venv/bin/activate
```

```bash
.venv\Scripts\activate
```

```bash
uv pip install ra-aid
```

--------------------------------

### Full Review-and-Approve Workflow Example

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

This demonstrates the complete planning workflow: generate a plan, extract it for review, and then execute the task if satisfied. It also shows how to use a custom project state directory.

```bash
# Full review-and-approve workflow
ra-aid -m "Migrate authentication from JWT to OAuth2" --research-and-plan-only
ra-aid extract-last-plan > migration-proposal.md
# (Review migration-proposal.md, then execute if satisfied:)
ra-aid -m "Migrate authentication from JWT to OAuth2"

# With custom project state directory
ra-aid -m "Build API" --research-and-plan-only \
  --project-state-dir ~/my-project-state
ra-aid extract-last-plan --project-state-dir ~/my-project-state
```

--------------------------------

### Iterative Planning Example

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/planning-workflow.md

Illustrates how to refine plans through multiple iterations. Generate an initial plan, review it, and then generate an improved plan based on feedback or new requirements.

```bash
# 1. Generate initial plan
ra-aid -m "Build a weather CLI tool" --research-and-plan-only

# 2. Extract and review
ra-aid extract-last-plan
# (Decide the plan needs more features)

# 3. Generate improved plan
ra-aid -m "Build a weather CLI tool with current weather and 3-day forecast" --research-and-plan-only

# 4. Extract final plan
ra-aid extract-last-plan > weather-cli-plan.md
```

--------------------------------

### Use OpenRouter Provider with RA.Aid

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

This example demonstrates using the OpenRouter provider with RA.Aid. Ensure `OPENROUTER_API_KEY` is set.

```bash
ra-aid -m "Your task" --provider openrouter --model mistralai/mistral-large-2411
```

--------------------------------

### Plan and Document a New Feature

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/planning-workflow.md

This example illustrates planning a complex new feature, saving both the plan and research notes to separate files for comprehensive documentation and review.

```bash
# Plan a complex feature
ra-aid -m "Add real-time chat functionality to the web app" --research-and-plan-only
```

```bash
# Save comprehensive documentation
ra-aid extract-last-plan > chat-feature-plan.md
ra-aid extract-last-research-notes > chat-research.md
```

```bash
# Review both files before implementation
```

--------------------------------

### Use Gemini as Expert

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Configure the EXPERT_GEMINI_API_KEY environment variable. This example demonstrates using Gemini's 2.5-pro model for expert assistance.

```bash
export EXPERT_GEMINI_API_KEY='your_gemini_key'
ra-aid -m "Fix performance bottleneck" \
  --expert-provider gemini --expert-model gemini-2.5-pro-preview-05-06
```

--------------------------------

### Log Message Example

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/configuration/logging.md

An example of a log message following the standard format, indicating a warning about a command execution timeout.

```text
2025-03-01 14:30:27,123 - ra_aid.agent_utils - WARNING - Command execution timeout after 60 seconds
```

--------------------------------

### Install RA.Aid on Windows

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

Installs the RA.Aid Python package and its Windows-specific dependency, pywin32, using pip.

```powershell
pip install ra-aid
pip install pywin32
```

--------------------------------

### Start RA.Aid Web UI with Default Settings

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/web-ui.md

Launches the RA.Aid web server using default host (0.0.0.0) and port (1818). Access the UI via the provided URL in your browser.

```bash
# Start with default settings (0.0.0.0:1818)
ra-aid --server
```

--------------------------------

### Launch RA.Aid Server with Web Interface

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

Start the RA.Aid server with its web interface using the --server flag. You can specify custom host and port with --server-host and --server-port.

```bash
# Start with default settings (0.0.0.0:1818)
ra-aid --server
```

```bash
# Specify custom host and port
ra-aid --server --server-host 127.0.0.1 --server-port 3000
```

--------------------------------

### Verify RA.Aid Installation

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Check if RA.Aid has been installed correctly by running the version command in your terminal.

```bash
# Verify installation
ra-aid --version
# Output: ra-aid 0.30.2
```

--------------------------------

### Define MCP Server Integration Tools

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Integrate with MultiServerMCPClient for advanced tools. This example shows setting up connections to different MCP servers and retrieving their tools.

```python
# tools/mcp_tools.py — MCP server integration for advanced tools
from ra_aid.utils.mcp_client import MultiServerMCPClient_Sync

mcp_client = MultiServerMCPClient_Sync({
    "mcp-example-server": {
        "transport": "stdio",
        "command": "python",
        "args": ["./examples/custom-tools-mcp/mcp_server.py"],
    },
    "mcp-weather": {
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@smithery/cli@latest", "run", "@mcp-examples/weather"],
    },
})

mcp_tools = mcp_client.get_tools_sync()
tools = mcp_tools
```

--------------------------------

### Install Ollama and Pull Models

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Before running RA.Aid with Ollama, ensure Ollama is installed and pull the desired models using the `ollama pull` command.

```bash
ollama pull justinledwards/mistral-small-3.1-Q6_K
ollama pull qwq:32b
```

--------------------------------

### Get Server Configuration

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/api/get-config-config-get.api.mdx

Retrieves the server's configuration details.

```APIDOC
## GET /config

### Description
Return server configuration including host and port.

### Method
GET

### Endpoint
/config

### Response
#### Success Response (200)
- **host** (string) - The hostname or IP address of the server.
- **port** (integer) - The port number the server is listening on.
```

--------------------------------

### Get Root

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/api/get-root-get.api.mdx

Serves the index.html file. It can optionally accept a port parameter.

```APIDOC
## GET /

### Description
Serve the index.html file with port parameter.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **content** (string) - The content of the index.html file.
```

--------------------------------

### OpenGL Window Initialization and Render Loop (C++)

Source: https://github.com/ai-christianson/ra.aid/blob/master/tests/data/valid_function_calls.txt

This C++ code initializes GLFW, creates an OpenGL window, and sets up a basic render loop. It includes input processing and window resizing callbacks. Ensure GLFW is properly installed and configured.

```cpp
#include <GLFW/glfw3.h>
#include <iostream>

void framebuffer_size_callback(GLFWwindow* window, int width, int height);
void processInput(GLFWwindow *window);

// settings
const unsigned int SCR_WIDTH = 800;
const unsigned int SCR_HEIGHT = 600;

int main()
{
    // glfw: initialize and configure
    glfwInit();
    glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
    glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 3);
    glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);

#ifdef __APPLE__
    glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, GL_TRUE);
#endif

    // glfw window creation
    GLFWwindow* window = glfwCreateWindow(SCR_WIDTH, SCR_HEIGHT, "LearnOpenGL", NULL, NULL);
    if (window == NULL)
    {
        std::cout << "Failed to create GLFW window" << std::endl;
        glfwTerminate();
        return -1;
    }
    glfwMakeContextCurrent(window);
    glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);

    // glad: load all OpenGL function pointers
    // gladLoadGLLoader((GLADloadproc)glfwGetProcAddress);
    // if (!gladLoadGLLoader((GLADloadproc)glfwGetProcAddress))
    // {
    //     std::cout << "Failed to initialize GLAD" << std::endl;
    //     return -1;
    // }

    // render loop
    while (!glfwWindowShouldClose(window))
    {
        // input
        processInput(window);

        // render
        glClearColor(0.2f, 0.3f, 0.3f, 1.0f);
        glClear(GL_COLOR_BUFFER_BIT);

        // glfw: swap buffers and poll IO events (keys pressed/released, mouse moved etc.)
        glfwSwapBuffers(window);
        glfwPollEvents();
    }

    // glfw: terminate, clearing all previously allocated GLFW resources.
    glfwTerminate();
    return 0;
}

// process all input: query GLFW whether relevant keys are pressed/released this frame and react accordingly
void processInput(GLFWwindow *window)
{
    if (glfwGetKey(window, GLFW_KEY_ESCAPE) == GLFW_PRESS)
        glfwSetWindowShouldClose(window, true);
}

// glfw: whenever the window size changed (by OS or user resize) this callback function executes
void framebuffer_size_callback(GLFWwindow* window, int width, int height)
{
    // make sure the viewport matches the new window dimensions; note that width and 
    // height will be significantly larger than specified on retina displays.
    glViewport(0, 0, width, height);
}

```

--------------------------------

### Run version-json script

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/scripts/README.md

Execute the version-json script to generate a version.json file. This script is part of the build and start processes.

```bash
npm run version-json
```

```bash
node scripts/version.js
```

--------------------------------

### Integrate Advanced Tools with MCP

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/custom-tools.md

Dynamically add complex tools by configuring MCP servers. This example uses `MultiServerMCPClient_Sync` to connect to an MCP server and retrieve tools.

```python
# tools/custom_tools.py
from ra_aid.utils.mcp_client import MultiServerMCPClient_Sync

mcp_client = MultiServerMCPClient_Sync({
    "mcp-example-server": {
        "transport": "stdio",
        "command": "python",
        "args": ["./examples/custom-tools-mcp/mcp_server.py"],
    },
    "mcp-weather": {
        "transport": "stdio",
        "command": "npx",
        "args": [
            "-y",
            "@smithery/cli@latest",
            "run",
            "@mcp-examples/weather",
        ]
    },
})

mcp_tools = mcp_client.get_tools_sync()

tools = mcp_tools
```

--------------------------------

### Set Environment Variables for RA.Aid

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/recommended.md

Configure your API keys as environment variables. The `GEMINI_API_KEY` is required for the recommended setup. `TAVILY_API_KEY` is optional for web search.

```bash
export GEMINI_API_KEY='your_gemini_api_key'

export TAVILY_API_KEY='your_tavily_api_key'
```

--------------------------------

### Get Config

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Retrieve the current runtime configuration of the server, including provider, model, and feature flags.

```APIDOC
## GET /config

### Description
Retrieve the current runtime configuration of the server.

### Method
GET

### Endpoint
/config

### Response
#### Success Response (200)
- **body** (object) - Current provider, model, feature flags, etc.
```

--------------------------------

### Customize RA.Aid Web UI Host and Port

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/web-ui.md

Starts the RA.Aid web server with a specified host and port. Useful for accessing the UI from different machines or avoiding port conflicts.

```bash
# Specify custom host and port
ra-aid --server --server-host 127.0.0.1 --server-port 3000
```

--------------------------------

### Cross-Project Knowledge Sharing Example

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/configuration/project-state.md

Use a shared project state directory to leverage knowledge across related projects. This allows RA.Aid to maintain a consistent knowledge base for multiple, interconnected projects.

```bash
# Working on project A with shared knowledge
ra-aid -m "Implement feature" --project-state-dir ~/shared-ra-aid

# Later, working on project B with the same knowledge base
cd ~/project-B
ra-aid -m "Implement similar feature" --project-state-dir ~/shared-ra-aid
```

--------------------------------

### Reset Project Memory with Custom State Directory

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/configuration/project-state.md

Combine `--project-state-dir` with `--wipe-project-memory` to start with a clean slate in a specified directory. This is helpful for troubleshooting or when beginning a new task.

```bash
ra-aid -m "Fresh start" --project-state-dir ~/custom-state --wipe-project-memory
```

--------------------------------

### Start RA.Aid in Interactive Chat Mode

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/recommended.md

Launch RA.Aid to engage in an interactive chat session. This is useful for multi-turn conversations and complex tasks.

```bash
ra-aid --chat
```

--------------------------------

### Run Frontend Development Server

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/contributing.md

Start the frontend development server using yarn. This command runs the web app on the default Vite port (5173) and targets the backend on port 1818.

```bash
cd frontend/
yarn dev
```

--------------------------------

### Set Optional Environment Variables for RA.Aid

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/recommended.md

Configure optional API keys for alternative providers like OpenAI and Anthropic, or for specific expert models. These are not required for the basic recommended setup.

```bash
export OPENAI_API_KEY='your_openai_api_key'

export ANTHROPIC_API_KEY='your_anthropic_api_key'

# Optional: For OpenAI
# export EXPERT_OPENAI_API_KEY='your_openai_api_key_for_expert'
# Optional: For Gemini
# export EXPERT_GEMINI_API_KEY='your_gemini_api_key_for_expert'
```

--------------------------------

### Launch RA.Aid Web Server

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Start the RA.Aid web server using the `--server` flag. You can specify custom host and port, enable `--cowboy-mode` for auto-execution of shell commands, or use it for programmatic interaction via the REST API.

```bash
# Start server on default host:port (0.0.0.0:1818)
ra-aid --server
```

```bash
# Custom host and port
ra-aid --server --server-host 127.0.0.1 --server-port 3000
```

```bash
# Server with cowboy mode (auto-executes shell commands — confirm prompt shown)
ra-aid --server --cowboy-mode
```

```bash
# Open browser to: http://localhost:1818
```

--------------------------------

### Add shadcn/ui Components with RA.Aid

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/modern-web-app.md

Install and configure shadcn/ui in your Next.js project using RA.Aid. This command also adds initial shadcn components to your main page.

```bash
ra-aid -m "Install shadcn into this project and put a few examples of shadcn components on the main page."
```

--------------------------------

### Set Up Virtual Environment

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/contributing.md

Create and activate a Python virtual environment for development.

```bash
python -m venv venv
source venv/bin/activate
```

--------------------------------

### Integrate Prisma with SQLite using RA.Aid

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/modern-web-app.md

Integrate Prisma ORM with SQLite into your Next.js project. RA.Aid handles Prisma setup, schema creation, and initial model configuration.

```bash
ra-aid -m "Integrate prisma/sqlite into this project."
```

--------------------------------

### Install ripgrep on Windows

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

Installs the ripgrep utility on Windows using Chocolatey. Ensure Chocolatey is installed first and PowerShell is run as administrator.

```powershell
# Install Chocolatey if not already installed (run in admin PowerShell)
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install ripgrep using Chocolatey
choco install ripgrep
```

--------------------------------

### Enable Reasoning Assistance with Ollama

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Use the --reasoning-assistance flag along with specified expert and main models to enable the expert to guide tool selection, especially for less capable main models.

```bash
ra-aid --provider ollama --model justinledwards/mistral-small-3.1-Q6_K \
  --expert-provider ollama --expert-model qwq:32b \
  --reasoning-assistance \
  -m "Implement OAuth2 login flow"
```

--------------------------------

### Run RA.Aid with Aider Integration

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/recommended.md

Use RA.Aid with the `--use-aider` flag to leverage aider's specialized code editing capabilities instead of RA.Aid's built-in file modification tools. Ensure aider is installed separately.

```bash
ra-aid -m "Implement this feature" --use-aider
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

Set up a Python virtual environment for the project. Use `venv\Scripts\activate` on Windows.

```bash
python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`
```

--------------------------------

### Normal Execution Workflow: Plan, Review, Execute

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/planning-workflow.md

This workflow demonstrates the typical cycle of planning, reviewing, and executing a task using RA.Aid. First, generate and extract the plan, then execute the task if the plan is satisfactory.

```bash
# Plan phase
ra-aid -m "Add error handling to database module" --research-and-plan-only
```

```bash
# Review phase
ra-aid extract-last-plan
```

```bash
# Execution phase (if plan looks good)
ra-aid -m "Add error handling to database module"
```

--------------------------------

### Set Up Google Gemini API Key

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/open-models.md

Set the GEMINI_API_KEY environment variable to authenticate with Google Gemini.

```bash
export GEMINI_API_KEY=your_api_key_here
```

--------------------------------

### Example: Explicit Think Tags in Response

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/configuration/thinking-models.md

This is an example of a model's response containing explicit think tags. RA.Aid will parse and display the content within the tags separately.

```text
<think>
Let me analyze the existing error handling logic:
1. Current approach uses try/except blocks scattered throughout
2. Error messages are inconsistent
3. There's no central logging mechanism
I should suggest a unified error handling approach with proper logging.
</think>

I recommend refactoring the error handling logic by implementing a centralized error handler...

```

--------------------------------

### Use MakeHub with Temperature Control

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/open-models.md

Use MakeHub for curated models and configure temperature for creative vs. deterministic responses.

```bash
ra-aid -m "Your task" --provider makehub --model anthropic/claude-4-sonnet --temperature 0.3
```

--------------------------------

### REST API: Get Session Details

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Retrieve details for a specific session by its ID using `GET /v1/session/{session_id}`. The response includes command line, program version, and display name.

```bash
curl http://localhost:1818/v1/session/42
# Response (200):
# {
#   "id": 42,
#   "created_at": "2025-05-06T12:00:00Z",
#   "updated_at": "2025-05-06T12:05:00Z",
#   "start_time": "2025-05-06T12:00:00Z",
#   "command_line": "ra-aid -m 'Add error handling'",
#   "program_version": "0.30.2",
#   "display_name": "Add error handling to the database module"
# }
```

--------------------------------

### REST API: Get Session Trajectories

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Retrieve all trajectory records, including tool calls and stage transitions, for a specific session using `GET /v1/session/{session_id}/trajectory`. The response is an array of TrajectoryModel objects.

```bash
curl http://localhost:1818/v1/session/42/trajectory
# Response (200): Array of TrajectoryModel objects
# [
#   {
#     "id": 101,

```

--------------------------------

### Wipe Project Memory

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Use `--wipe-project-memory` to clear all stored facts, snippets, and notes before starting a new session. This is useful after major refactoring or when starting a completely new task. You can also specify a custom state directory.

```bash
# Wipe all stored memory before starting a new session
ra-aid --wipe-project-memory -m "Update the authentication system"
```

```bash
# Wipe memory after major refactoring
ra-aid --wipe-project-memory -m "Start greenfield rewrite of data pipeline"
```

```bash
# Use a custom state directory (database stored at /path/to/dir/pk.db)
ra-aid -m "Your task" --project-state-dir /path/to/custom/directory
```

```bash
# Wipe memory in custom directory
ra-aid --wipe-project-memory \
  --project-state-dir /path/to/custom/directory \
  -m "Begin new feature set"
```

```bash
# Check memory stats (shown in status panel at startup):
# 💾 Memory: 12 facts, 8 snippets, 4 notes
ra-aid -m "Show current project structure"
```

--------------------------------

### Get Session Trajectories

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/api/get-session-trajectories-v-1-session-session-id-trajectory-get.api.mdx

Fetches all trajectories for a given session ID.

```APIDOC
## GET /ai-christianson/ra.aid/session/{session_id}/trajectory

### Description
Retrieves all trajectories associated with a specific session.

### Method
GET

### Endpoint
/ai-christianson/ra.aid/session/{session_id}/trajectory

### Parameters
#### Path Parameters
- **session_id** (integer) - Required - The unique identifier of the session.

### Response
#### Success Response (200)
- **[]** (array) - An array of Trajectory objects.

**TrajectoryModel**
- **id** (integer) - Unique identifier for the trajectory
- **created_at** (string) - When the record was created
- **updated_at** (string) - When the record was last updated
- **human_input_id** (integer) - Optional reference to the associated human input
- **tool_name** (string) - Name of the tool that was executed
- **tool_parameters** (string) - Dictionary containing the parameters passed to the tool
- **tool_result** (string) - Dictionary containing the result returned by the tool
- **step_data** (string) - Dictionary containing UI rendering data
- **record_type** (string) - Type of trajectory record
- **current_cost** (number) - Optional cost of the last LLM message
- **input_tokens** (integer) - Optional input/prompt token usage
- **output_tokens** (integer) - Optional output/completion token usage
- **is_error** (boolean) - Flag indicating if this record represents an error
- **error_message** (string) - The error message if is_error is True
- **error_type** (string) - The type/class of the error if is_error is True
- **error_details** (string) - Additional error details if is_error is True
- **session_id** (integer) - Optional reference to the associated session

#### Response Example
```json
[
  {
    "id": 1,
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:05:00Z",
    "human_input_id": null,
    "tool_name": "search",
    "tool_parameters": "{\"query\": \"latest AI news\"}",
    "tool_result": "{\"results\": [\"...\", \"...\"]}",
    "step_data": "{\"display\": \"list\"}",
    "record_type": "tool_call",
    "current_cost": 0.05,
    "input_tokens": 1000,
    "output_tokens": 500,
    "is_error": false,
    "error_message": null,
    "error_type": null,
    "error_details": null,
    "session_id": 123
  }
]
```

#### Error Response
- **404** - Session not found
- **422** - Validation error
- **500** - Database error
```

--------------------------------

### Set Up OpenRouter API Key

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/open-models.md

Set the OPENROUTER_API_KEY environment variable to authenticate with OpenRouter.

```bash
export OPENROUTER_API_KEY=your_api_key_here
```

--------------------------------

### Get session trajectories

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/api/get-session-trajectories-v-1-session-session-id-trajectory-get.api.mdx

Fetches all trajectory records for a specific session.

```APIDOC
## GET /v1/session/{session_id}/trajectory

### Description
Get all trajectory records associated with a specific session

### Method
GET

### Endpoint
/v1/session/{session_id}/trajectory

### Parameters
#### Path Parameters
- **session_id** (integer) - Required - The ID of the session to retrieve trajectories for.

### Response
#### Success Response (200)
- **field1** (type) - Description
```

--------------------------------

### Implement C++ Hello World Program

Source: https://github.com/ai-christianson/ra.aid/blob/master/tests/data/think-tag/sample_1.txt

Use this function to create a C++ file with a 'Hello, World!' program. The task specification includes file creation, code content, and acceptance criteria for compilation and execution.

```python
request_task_implementation('''Create a C++ source file named main.cpp containing a standard "Hello World" program.

Steps:
1. Create file main.cpp
2. Add the following content:
#include <iostream>
using namespace std;

int main() {
    cout << "Hello, world!" << endl;
    return 0;
}

Acceptance Criteria:
- The program compiles without errors using g++ main.cpp -o hello
- Running ./hello outputs exactly "Hello, world!" followed by a newline
''')
```

--------------------------------

### Initialize Next.js App with RA.Aid

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/modern-web-app.md

Use this command to initialize a new Next.js project with RA.Aid. It sets up a clean project following best practices and reads the latest Next.js documentation.

```bash
ra-aid -m "Initialize a new nextjs app."
```

--------------------------------

### Get Session by ID

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/api/get-session-v-1-session-session-id-get.api.mdx

Retrieves the details of a specific session using its unique identifier.

```APIDOC
## GET /v1/session/{session_id}

### Description
Get a specific session by ID

### Method
GET

### Endpoint
/v1/session/{session_id}

### Parameters
#### Path Parameters
- **session_id** (integer) - Required - Unique identifier for the session

#### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the session
- **created_at** (string) - When the session record was created
- **updated_at** (string) - When the session record was last updated
- **start_time** (string) - When the program session started
- **command_line** (string) - Command line arguments used to start the program
- **program_version** (string) - Version of the program
- **machine_info** (string) - Dictionary containing machine-specific metadata
- **display_name** (string) - Display name for the session (derived from human input or command line)

#### Response Example
```json
{
  "id": 1,
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:05:00Z",
  "start_time": "2023-10-27T10:01:00Z",
  "command_line": "python my_script.py --input data.csv",
  "program_version": "1.2.0",
  "machine_info": "{\"cpu\": \"Intel i7\", \"ram\": \"16GB\"}",
  "display_name": "Data Processing Script"
}
```
```

--------------------------------

### Run Frontend Development Server with Custom Ports

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/contributing.md

Configure and run the frontend development server with custom ports for both the web app and the backend API.

```bash
# run development server on port 5173
cd frontend/ 
yarn dev

# run development bundle for other ports
# (the prebuilt bundle from uvicorn always serves both frontend and backend on --server-port argument)
VITE_FRONTEND_PORT=5555 yarn dev  # hosts web app on 5555 targeting backend on 1818
VITE_FRONTEND_PORT=2221 VITE_BACKEND_PORT=9191 yarn dev  # hosts web app on 2221 targeting backend on 9191
VITE_BACKEND_PORT=4002 yarn dev  # hosts web app on 5173 (vite default port) targeting backend on 4002
yarn dev  # hosts web app on 5173 (default) targeting backend on 1818
```

--------------------------------

### REST API: Get Session

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Retrieve detailed information about a specific session using its unique `session_id`.

```APIDOC
### REST API: Get Session — `GET /v1/session/{session_id}`

Retrieve details of a specific session by its integer ID.

```bash
curl http://localhost:1818/v1/session/42
# Response (200):
# {
#   "id": 42,
#   "created_at": "2025-05-06T12:00:00Z",
#   "updated_at": "2025-05-06T12:05:00Z",
#   "start_time": "2025-05-06T12:00:00Z",
#   "command_line": "ra-aid -m 'Add error handling'",
#   "program_version": "0.30.2",
#   "display_name": "Add error handling to the database module"
# }
```
```

--------------------------------

### REST API: Spawn Agent

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Programmatically start an agent task via the REST API. Returns a `session_id` to track progress.

```APIDOC
### REST API: Spawn Agent — `POST /v1/spawn-agent`

Programmatically start an agent task. Returns a `session_id` to track progress.

```bash
# Spawn a new agent task
curl -X POST http://localhost:1818/v1/spawn-agent \
  -H "Content-Type: application/json" \
  -d '{"message": "Add error handling to the database module", "research_only": false}'
# Response (201):
# {"session_id": "42"}

# Research-only task via API
curl -X POST http://localhost:1818/v1/spawn-agent \
  -H "Content-Type: application/json" \
  -d '{"message": "Explain the authentication flow", "research_only": true}'
# Response (201):
# {"session_id": "43"}
```
```

--------------------------------

### Extract Latest Research Notes

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Use `ra-aid extract-last-research-notes` to get the research findings from the latest session. The output can be redirected to a file.

```bash
# Extract research notes from the latest session
ra-aid extract-last-research-notes > research-findings.md
```

--------------------------------

### Build Static Website

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/README.md

Generates static content for deployment. The output is placed in the 'build' directory.

```bash
yarn build
```

--------------------------------

### Use OpenAI-Compatible Provider

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/open-models.md

Connect to custom OpenAI-compatible API endpoints.

```bash
ra-aid -m "Your task" --provider openai-compatible --model your-model-name
```

--------------------------------

### RA.Aid Code Research Example

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

Perform code research by specifying the analysis task with --message and using the --research-only flag.

```bash
ra-aid -m "Analyze the current error handling patterns" --research-only
```

--------------------------------

### REST API: Get Session Trajectories

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Retrieve all trajectory records, including tool calls, stage transitions, and errors, for a specific session.

```APIDOC
### REST API: Get Session Trajectories — `GET /v1/session/{session_id}/trajectory`

Retrieve all trajectory records (tool calls, stage transitions, errors) for a session.

```bash
curl http://localhost:1818/v1/session/42/trajectory
# Response (200): Array of TrajectoryModel objects
# [
#   {
#     "id": 101,

```

--------------------------------

### Wipe Project Memory

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/configuration/memory-management.md

Use this command to clear RA.Aid's memory for the current project. This is useful after refactoring or when starting a new development phase.

```bash
ra-aid --wipe-project-memory -m "Update the authentication system"
```

```bash
# Before starting work on a new major feature
ra-aid --wipe-project-memory -m "Implement payment processing system"
```

--------------------------------

### Web Server / REST API (--server)

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Launch a FastAPI server to enable browser-based and programmatic interaction with RA.Aid.

```APIDOC
## Web Server / REST API (`--server`)

Launch a FastAPI server with a web UI for browser-based and programmatic interaction.

```bash
# Start server on default host:port (0.0.0.0:1818)
ra-aid --server

# Custom host and port
ra-aid --server --server-host 127.0.0.1 --server-port 3000

# Server with cowboy mode (auto-executes shell commands — confirm prompt shown)
ra-aid --server --cowboy-mode

# Open browser to: http://localhost:1818
```
```

--------------------------------

### Use Anthropic Provider with RA.Aid

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

This example shows how to use the default Anthropic provider or explicitly specify an Anthropic model. The default model is 'claude-3-7-sonnet-20250219'.

```bash
# Uses default model (claude-3-7-sonnet-20250219)
ra-aid -m "Your task"

# Or explicitly specify:
ra-aid -m "Your task" --provider anthropic --model claude-3-5-sonnet-20241022
```

--------------------------------

### Configure Project State and Logging

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/configuration/project-state.md

Set a custom project state directory and configure logging options simultaneously. This allows for detailed debugging in an isolated environment.

```bash
ra-aid -m "Debug issue" --project-state-dir ~/debug-state --log-level debug --pretty-logger
```

--------------------------------

### Get Server Configuration - REST API

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Retrieve the current runtime configuration of the server. This endpoint is useful for understanding the server's operational state.

```bash
curl http://localhost:1818/config
```

--------------------------------

### Configure Expert Model via Command Line

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/configuration/expert-model.md

Use command line arguments to specify the AI provider and model for expert queries. This allows for direct control over the expert model's identity.

```bash
ra-aid --expert-provider anthropic --expert-model claude-3-7-sonnet-20250219
```

--------------------------------

### REST API: List Sessions

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Retrieve a paginated list of all sessions using `GET /v1/session`. You can control pagination with `offset` and `limit` query parameters.

```bash
# Default: offset=0, limit=10
curl "http://localhost:1818/v1/session"
```

```bash
# Paginate: skip first 10, get next 5
curl "http://localhost:1818/v1/session?offset=10&limit=5"
# Response (200):
# {
#   "total": 43,
#   "items": [...],
#   "limit": 5,
#   "offset": 10
# }
```

--------------------------------

### Create a Simple Custom Tool

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/usage/custom-tools.md

Define custom tools in a Python file, exporting a list named `tools`. Each tool should be decorated with `@tool` and include a clear docstring and type hints.

```python
# tools/custom_tools.py
from langchain_core.tools import tool

@tool
def custom_add(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

tools = [
    custom_add,
]
```

--------------------------------

### RA.Aid Automated Updates Example

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

Automate code updates by specifying the task in the --message option and using --cowboy-mode to bypass interactive confirmations.

```bash
ra-aid -m "Update deprecated API calls across the entire codebase" --cowboy-mode
```

--------------------------------

### RA.Aid Code Analysis Example

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

Use the --message option to specify a task for code analysis and --research-only to perform research without implementation.

```bash
ra-aid -m "Explain how the authentication middleware works" --research-only
```

--------------------------------

### Run RA.Aid with a Provider

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/open-models.md

Execute RA.Aid with a specified task, provider, and model. Replace <provider> and <model> with your chosen options.

```bash
ra-aid -m "Your task" --provider <provider> --model <model>
```

--------------------------------

### Basic Usage (Default Logging)

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/configuration/logging.md

This command uses the default logging settings, which include file logging with warnings and errors shown on the console.

```bash
ra-aid -m "Add new feature"
```

--------------------------------

### Include Core Libraries in C++

Source: https://github.com/ai-christianson/ra.aid/blob/master/tests/data/test_case_1.txt

Include necessary libraries for GLFW, OpenGL, and standard I/O operations in your C++ project. Ensure these libraries are correctly installed and linked.

```cpp
#include <GLFW/glfw3.h>
#include <GL/gl.h>
#include <iostream>

```

--------------------------------

### RA.Aid Complex Changes Example

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

Execute complex code modifications by providing a detailed message and enabling --cowboy-mode to skip interactive approval for shell commands.

```bash
ra-aid -m "Refactor the database connection code to use connection pooling" --cowboy-mode
```

--------------------------------

### Use Ollama with Different Models and Context

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/quickstart/open-models.md

Run large language models locally using Ollama. Adjust context window with --num-ctx.

```bash
ra-aid -m "Your task" --provider ollama --model justinledwards/mistral-small-3.1-Q6_K
```

```bash
ra-aid -m "Your task" --provider ollama --model qwq:32b --num-ctx 8192
```

```bash
ra-aid -m "Your task" --provider ollama --model MHKetbi/Qwen2.5-Coder-32B-Instruct --temperature 0.3
```

--------------------------------

### Run RA.Aid with Custom Tools

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Execute RA.Aid with custom tools by specifying the path to the Python file containing the tool definitions using the --custom-tools flag.

```bash
# Run RA.Aid with custom tools
ra-aid --custom-tools tools/custom_tools.py \
  -m "Query the database for all users created this week and summarize"
```

--------------------------------

### Memory Management (--wipe-project-memory)

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Manage RA.Aid's persistent memory by wiping it before starting a new session or after major changes. This command clears the local SQLite database.

```APIDOC
## Memory Management (`--wipe-project-memory`)

RA.Aid persists key facts, code snippets, and research notes in a local SQLite database (`.ra-aid/pk.db`) across sessions. Automatic garbage collection triggers when thresholds are exceeded (facts > 50, snippets > 35, notes > 30).

```bash
# Wipe all stored memory before starting a new session
ra-aid --wipe-project-memory -m "Update the authentication system"

# Wipe memory after major refactoring
ra-aid --wipe-project-memory -m "Start greenfield rewrite of data pipeline"

# Use a custom state directory (database stored at /path/to/dir/pk.db)
ra-aid -m "Your task" --project-state-dir /path/to/custom/directory

# Wipe memory in custom directory
ra-aid --wipe-project-memory \
  --project-state-dir /path/to/custom/directory \
  -m "Begin new feature set"

# Check memory stats (shown in status panel at startup):
# 💾 Memory: 12 facts, 8 snippets, 4 notes
ra-aid -m "Show current project structure"
```
```

--------------------------------

### Use Makehub Provider with RA.Aid

Source: https://github.com/ai-christianson/ra.aid/blob/master/README.md

Configure RA.Aid to use the Makehub provider. You can optionally specify a price-performance ratio for model selection.

```bash
ra-aid -m "Your task" --provider makehub --model openai/gpt-4o

# With price-performance optimization
ra-aid -m "Your task" --provider makehub --model anthropic/claude-4-sonnet --price-performance-ratio 0.7
```

--------------------------------

### REST API: Spawn Agent

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Programmatically start an agent task using `POST /v1/spawn-agent`. Provide a message and optionally set `research_only` to true. The response includes a `session_id` for tracking.

```bash
# Spawn a new agent task
curl -X POST http://localhost:1818/v1/spawn-agent \
  -H "Content-Type: application/json" \
  -d '{"message": "Add error handling to the database module", "research_only": false}'
# Response (201):
# {"session_id": "42"}
```

```bash
# Research-only task via API
curl -X POST http://localhost:1818/v1/spawn-agent \
  -H "Content-Type: application/json" \
  -d '{"message": "Explain the authentication flow", "research_only": true}'
# Response (201):
# {"session_id": "43"}
```

--------------------------------

### Hybrid Model Configuration: Local Main + Cloud Expert

Source: https://context7.com/ai-christianson/ra.aid/llms.txt

Combine a local Ollama model for the main agent with a cloud-based model (e.g., Anthropic Claude) for expert queries.

```bash
ra-aid --provider ollama --model justinledwards/mistral-small-3.1-Q6_K \
  --expert-provider anthropic --expert-model claude-3-7-sonnet-20250219 \
  -m "Implement complex caching strategy"
```

--------------------------------

### Project-Specific Knowledge Isolation Example

Source: https://github.com/ai-christianson/ra.aid/blob/master/docs/docs/configuration/project-state.md

Keep project knowledge separate for unrelated projects by assigning a unique state directory to each. This prevents knowledge overlap and maintains distinct project contexts.

```bash
# For project A
cd ~/project-A
ra-aid -m "Work on Project A" --project-state-dir ~/project-A-ra-aid

# For project B
cd ~/project-B
ra-aid -m "Work on Project B" --project-state-dir ~/project-B-ra-aid
```