DOCSEARCHbyAlgolia
Submit Docs

RA.Aid Documentation

repository·master·Indexed 24 days ago

https://github.com/ai-christianson/ra.aid

RA.Aid is an autonomous software development agent built on LangGraph that utilizes a research-planning-implementation workflow for complex programming tasks, codebase analysis, and refactoring. It supports multiple LLM providers including Anthropic, OpenAI, and Gemini, and offers integration with aider, Model Context Protocol (MCP) servers for custom tools, and a web-based chat interface.

Tokens
39.4K
Snippets
91
Records
252
Agent score
80%

What's inside RA.Aid

  2. Overview of RA.Aid

    master

    RA.Aid (pronounced "raid") is a standalone coding agent designed for autonomous software development. Built on LangGraph's agent-based task execution framework, it assists with research, planning, and implementation of multi-step development tasks.

    It uses a three-stage architecture:

    1. Research: Analyzes codebases and gathers context.
    2. Planning: Breaks down tasks into specific, actionable steps.
    3. Implementation: Executes the plan with AI assistance.

    RA.Aid can optionally integrate with aider using the --use-aider flag to leverage specialized code editing capabilities.

  3. Key features of RA.Aid

    master

    RA.Aid is an autonomous coding agent with the following core capabilities:

    • Three-Stage Workflow: Executes tasks through Research, Planning, and Implementation phases.
    • Web Research: Automatically searches for best practices and solutions.
    • Interactive Mode: Allows for natural language conversation during the process.
    • Multiple AI Providers: Supports Gemini, OpenAI, Anthropic, and more.
    • Git Integration: Works with your version control system.
    • Standalone Code Agent: Includes built-in code modification capabilities.
    • Aider Integration: Can leverage aider's specialized code editing by using the --use-aider flag.

  4. What is Reasoning Assistance and how does it work?

    master

    Reasoning Assistance is a feature that helps weaker agent models make better decisions regarding tool usage and task planning. It works by using a stronger model (the expert model) to provide strategic guidance at the beginning of each agent stage (research, planning, and implementation).

    How it works internally:

    1. RA.Aid makes a one-off call to the expert model using a specialized prompt containing the task description, current stage, and available tools.
    2. The expert model's strategic guidance is incorporated into the main agent's prompt.
    3. The main agent executes the task guided by these recommendations.

    Reasoning Assistance vs. Expert Model:

    • Reasoning Assistance: Uses the expert model to improve the agent's process (tool selection and planning).
    • Expert Model: Used to solve domain-specific technical problems (debugging or complex implementation decisions) when the agent consults it directly.

  5. How tool pairs are preserved during trimming

    master

    To prevent 400 Bad Request errors from Claude's API, RA.Aid ensures that tool call pairs are never split during message trimming. A tool pair consists of an AIMessage containing a tool call and a subsequent ToolMessage containing the result.

    Preservation Mechanism

    1. Detection: The is_tool_pair() function identifies consecutive messages where the first is an AIMessage with a tool call and the second is a ToolMessage.
    2. Atomic Segmentation: The message history is segmented into atomic units: single messages or inseparable tool pairs.
    3. Boundary Protection: If a trimming boundary would split a tool pair, the num_messages_to_keep is automatically adjusted to include both messages.
    4. Validation: After trimming, the system validates that the last message is not an AIMessage with an unfulfilled tool call; if it is, the message is removed to maintain a valid state.

  6. How the Planning Workflow works

    master

    The planning workflow is a non-destructive way to use RA.Aid. It follows a specific lifecycle:

    1. Research Phase: The agent researches your task and gathers information.
    2. Research Notes: The agent calls emit_research_notes to store findings in the database.
    3. Plan Generation: The agent creates a detailed implementation plan.
    4. Plan Storage: The agent calls emit_plan to save the plan as markdown text in the plan field of the session table in the SQLite database (located at .ra-aid/pk.db by default).
    5. Automatic Exit: The agent exits without performing any file modifications or code execution.

    This allows for a Review and Approve pattern: generate the plan, extract it to a file, review it, and then run the original command without the --research-and-plan-only flag to execute the approved plan.

  7. How Thinking Models work in RA.Aid

    master

    RA.Aid supports models that reveal their internal reasoning process through two distinct implementation methods. This allows users to see the model's logic in separate "💭 Thoughts" panels, keeping the main response clean.

    1. Explicit Think Tags: Used by models like qwen-qwq-32b. These models wrap their reasoning in XML-style <think>...</think> tags. RA.Aid detects these tags and extracts the content for separate display.

    2. Native Thinking Mode: Used by advanced models like claude-3-7-sonnet-20250219. These models have thinking capabilities built into the API. RA.Aid sends specific configuration parameters (e.g., budget_tokens) to enable this mode, and the API returns structured content that RA.Aid separates into thinking and response components.

  8. How the Anthropic Token Limiter works in RA.Aid

    master

    The ra_aid/anthropic_token_limiter.py script manages and truncates message histories to prevent API errors caused by exceeding the token limits of language models (specifically Anthropic models).

    Core Workflow

    1. Token Counting: Uses litellm.token_counter to calculate the size of the message history. It uses convert_message_to_litellm_format to preprocess LangChain BaseMessage objects into a format compatible with litellm.
    2. Limit Determination: Dynamically fetches the max_input_tokens for the active model using get_model_token_limit. It queries litellm.get_model_info() first, falling back to a predefined models_params dictionary if necessary.
    3. Message Trimming: If the token count exceeds the limit, the state_modifier function triggers a trimming process via anthropic_trim_messages.

    Trimming Strategy

    • Preservation: The first two messages (typically the system prompt and initial user query) are always kept.
    • Tool Pair Integrity: The system ensures that tool call pairs (an AIMessage with a tool call followed by a ToolMessage with the result) are never split. They are treated as atomic units.
    • Direction: Trimming occurs from the oldest messages (the "last" messages in the history) until the total count falls within the max_input_tokens limit.

  9. Understand the Project State Directory structure

    master

    The project state directory contains the core components of RA.Aid's persistence and observability:

    • pk.db: A SQLite database acting as the core memory system. It stores project facts, code snippets (with file paths and line numbers), research notes, human input history, and configuration settings.
    • logs/: A directory containing timestamped log files (e.g., ra_aid_YYYYMMDD_HHMMSS.log) used for troubleshooting and monitoring agent behavior.

  10. Configure LLM Providers and Models

    master

    RA.Aid supports multiple LLM providers. By default, it uses Anthropic's Claude 3 Sonnet. For other providers, you must specify the --provider and the --model (the --model flag is required for all providers except Anthropic).

    Supported Providers:

    • anthropic (Default)
    • openai
    • openrouter
    • openai-compatible
    • makehub
    • gemini
    • deepseek (via direct provider or OpenRouter)

    Specialized Task Providers: You can override the default provider/model for specific sub-tasks using:

    • --research-provider / --research-model
    • --planner-provider / --planner-model
    • --expert-provider / --expert-model (for complex logic and debugging)

  11. Understand the VS Code extension file structure

    master

    A standard VS Code extension project contains these key files:

    • package.json: The manifest file. It is used to declare your extension, register commands, and define titles/command names so VS Code can display them in the command palette.
    • src/extension.ts: The main implementation file. It must export an activate function, which is called when the extension is first activated. Inside activate, you typically use registerCommand to bind logic to a command name.

  12. Configure Expert Models

    master

    Expert mode allows you to assign a specialized, typically more powerful and slower reasoning model to handle complex tasks. This is configured using --expert-provider and --expert-model flags.

    Environment Variables for Expert Keys:

    • EXPERT_DEEPSEEK_API_KEY
    • EXPERT_MAKEHUB_API_KEY
    • EXPERT_OPENROUTER_API_KEY
    • EXPERT_GEMINI_API_KEY

    Examples:

    • DeepSeek Expert: ra-aid -m "task" --expert-provider deepseek --expert-model deepseek-reasoner
    • MakeHub Expert: ra-aid -m "task" --expert-provider makehub --expert-model gpt-4o
    • Ollama Expert: ra-aid -m "task" --expert-provider ollama --expert-model qwq:32b
    # Example: Using OpenRouter as an expert
export EXPERT_OPENROUTER_API_KEY=your_key
ra-aid -m "Your task" --expert-provider openrouter --expert-model mistralai/mistral-large-2411